{ "schema_version": 2, "generated_at": "2026-08-23T13:27:11.851Z", "source_ref": "origin/staging", "summary": { "systems": 67, "repositories": 53, "deploy_targets": 122, "actions": 2069, "action_occurrences": 2301, "action_examples": 2069, "implemented_actions": 2032, "declared_unserved_actions": 32, "coverage_excluded_actions": 5, "uncatalogued_routes": 34, "action_coverage_configuration_findings": 34, "runtime_action_contracts": 2069, "runtime_action_audit_findings": 0, "mobile_contracts": 42, "notification_types": 328, "notification_occurrences": 360, "notification_examples": 328, "route_signals": 1860, "database_tables": 921, "test_cases": 30708, "shared_packages": 38, "package_entrypoints": 69, "package_exports": 1893, "package_source_findings": 0, "exceptions": 0 }, "systems": { "socialize": { "id": "socialize", "name": "Socialize", "slug": "socialize", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloSocialize" ], "source_revisions": [ { "source_path": "apps/TopoloSocialize", "repository": "apps/TopoloSocialize", "revision": "8a2994cc3a2d7b517df53e4a14f0fdb503ce8fe5", "ref": "origin/staging" } ], "source_counts": { "source_files": 445, "test_files": 151, "test_cases": 0, "migration_files": 17, "database_tables": 0, "manifests": 1, "deploy_targets": 3, "actions": 173, "mobile_contracts": 1, "notifications": 9, "package_manifests": 8, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloSocialize/topolo.app.json", "service_slug": "socialize", "name": "socialize", "app_id": "app_topolo_socialize", "compatibility_date": "2026-04-10", "primary_target": null, "environments": [ "development", "production", "staging" ], "targets": [ { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-socialize", "subdomain": "socialize", "healthcheck_path": null, "variable_names": [ "AUTH_API_URL", "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null } ] }, { "name": "api", "kind": "worker", "directory": "apps/api", "main": "dist/index.js", "worker_name": "topolo-socialize-api", "subdomain": "socialize-api", "healthcheck_path": "/health", "variable_names": [ "API_URL", "APP_URL", "ENVIRONMENT", "NEXUS_GATEWAY_URL", "ORG_SLUG", "TIKTOK_USE_SANDBOX", "TOPOLO_NOTIFY_URL", "TOPOLO_SEED_APP_ID" ], "secret_names": [], "bindings": [ { "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": "SOCIALIZE_AI_DB", "target": null }, { "kind": "d1", "binding": "SOCIALIZE_AUDIT_DB", "target": null }, { "kind": "r2", "binding": "MEDIA_BUCKET", "target": null }, { "kind": "r2", "binding": "BACKUP_BUCKET", "target": null }, { "kind": "kv", "binding": "SESSIONS_KV", "target": null }, { "kind": "kv", "binding": "CACHE_KV", "target": null }, { "kind": "vectorize", "binding": "VOICE_CONTEXT_INDEX", "target": null }, { "kind": "services", "binding": "BRAND_API", "target": null } ] }, { "name": "jobs", "kind": "worker", "directory": "apps/scheduler", "main": "dist/index.js", "worker_name": "topolo-socialize-scheduler", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "API_URL", "APP_URL", "ENVIRONMENT", "NEXUS_GATEWAY_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "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": "SOCIALIZE_AI_DB", "target": null }, { "kind": "d1", "binding": "SOCIALIZE_AUDIT_DB", "target": null }, { "kind": "r2", "binding": "MEDIA_BUCKET", "target": null }, { "kind": "kv", "binding": "SESSIONS_KV", "target": null }, { "kind": "kv", "binding": "CACHE_KV", "target": null } ] } ], "notifications": [ "socialize.brand.invitation.created", "socialize.campaign.completed", "socialize.campaign.scheduled", "socialize.integration.disconnected", "socialize.join_request.created", "socialize.post.approval_requested", "socialize.post.manual_publish_due", "socialize.post.publish_failed", "socialize.post.published" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_socialize", "events": [ { "type": "socialize.brand.invitation.created", "version": 1, "description": "An external collaborator was invited to a Socialize brand.", "status": "published", "payloadSchema": { "type": "object", "required": [ "recipient_email", "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "thread_key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "recipient_email": "collaborator@example.com", "title": "An external collaborator was invited to a Socialize brand.", "body": "Open the owning app to review this event.", "object_id": "object_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "confidential", "recipients": { "modes": [ "external" ], "externalAddress": "required" }, "idempotency": { "required": true, "pattern": "^socialize:brand-invite:" }, "sensitiveFields": [ "recipient_email", "cta_url" ] }, { "type": "socialize.campaign.completed", "version": 1, "description": "Socialize recorded the durable campaign completed transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string" }, "campaign_name": { "type": "string" }, "window_start_date": { "type": "string", "format": "date-time" }, "window_end_date": { "type": "string", "format": "date-time" }, "platform": { "type": "string" }, "platform_post_id": { "type": [ "string", "null" ] }, "disconnect_event_id": { "type": "string" }, "requester_name": { "type": [ "string", "null" ] }, "requester_email": { "type": "string", "format": "email" }, "source_type": { "type": "string" }, "failure_code": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "title": "Campaign completed", "body": "The campaign reached its durable completed state.", "object_type": "campaign", "object_id": "campaign_123", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^socialize:campaign:completed:" } }, { "type": "socialize.campaign.scheduled", "version": 1, "description": "Socialize recorded the durable campaign scheduled transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string" }, "campaign_name": { "type": "string" }, "window_start_date": { "type": "string", "format": "date-time" }, "window_end_date": { "type": "string", "format": "date-time" }, "platform": { "type": "string" }, "platform_post_id": { "type": [ "string", "null" ] }, "disconnect_event_id": { "type": "string" }, "requester_name": { "type": [ "string", "null" ] }, "requester_email": { "type": "string", "format": "email" }, "source_type": { "type": "string" }, "failure_code": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "title": "Campaign scheduled", "body": "The campaign schedule and its post runs were persisted.", "object_type": "campaign", "object_id": "campaign_123", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^socialize:campaign:scheduled:" } }, { "type": "socialize.integration.disconnected", "version": 1, "description": "Socialize recorded the durable integration disconnected transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string" }, "campaign_name": { "type": "string" }, "window_start_date": { "type": "string", "format": "date-time" }, "window_end_date": { "type": "string", "format": "date-time" }, "platform": { "type": "string" }, "platform_post_id": { "type": [ "string", "null" ] }, "disconnect_event_id": { "type": "string" }, "requester_name": { "type": [ "string", "null" ] }, "requester_email": { "type": "string", "format": "email" }, "source_type": { "type": "string" }, "failure_code": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "title": "Social account disconnected", "body": "A connected social account was durably disconnected.", "object_type": "integration", "object_id": "connection_123", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^socialize:integration:disconnected:" } }, { "type": "socialize.join_request.created", "version": 1, "description": "Socialize recorded the durable join request created transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string" }, "campaign_name": { "type": "string" }, "window_start_date": { "type": "string", "format": "date-time" }, "window_end_date": { "type": "string", "format": "date-time" }, "platform": { "type": "string" }, "platform_post_id": { "type": [ "string", "null" ] }, "disconnect_event_id": { "type": "string" }, "requester_name": { "type": [ "string", "null" ] }, "requester_email": { "type": "string", "format": "email" }, "source_type": { "type": "string" }, "failure_code": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "title": "New brand join request", "body": "A new request to join the brand was persisted.", "object_type": "join_request", "object_id": "join_123", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "confidential", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^socialize:join-request:created:" }, "sensitiveFields": [ "requester_email" ] }, { "type": "socialize.post.approval_requested", "version": 1, "description": "Socialize recorded the durable post approval requested transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string" }, "campaign_name": { "type": "string" }, "window_start_date": { "type": "string", "format": "date-time" }, "window_end_date": { "type": "string", "format": "date-time" }, "platform": { "type": "string" }, "platform_post_id": { "type": [ "string", "null" ] }, "disconnect_event_id": { "type": "string" }, "requester_name": { "type": [ "string", "null" ] }, "requester_email": { "type": "string", "format": "email" }, "source_type": { "type": "string" }, "failure_code": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "title": "Post ready for approval", "body": "A persisted post suggestion is ready for review.", "object_type": "post", "object_id": "post_123", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^socialize:post:approval-requested:" } }, { "type": "socialize.post.manual_publish_due", "version": 1, "description": "A post set to manual publishing reached its scheduled time. Socialize will not publish it — the Instagram Content Publishing API cannot attach sticker-based stories — so the operator is reminded to post it by hand.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string" }, "campaign_name": { "type": "string" }, "window_start_date": { "type": "string", "format": "date-time" }, "window_end_date": { "type": "string", "format": "date-time" }, "platform": { "type": "string" }, "platform_post_id": { "type": [ "string", "null" ] }, "disconnect_event_id": { "type": "string" }, "requester_name": { "type": [ "string", "null" ] }, "requester_email": { "type": "string", "format": "email" }, "source_type": { "type": "string" }, "failure_code": { "type": "string" }, "placement": { "type": "string" }, "scheduled_for": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "examples": [ { "title": "Post ready for you to publish", "body": "An instagram story is scheduled now and is set to manual publishing. Post it on the platform yourself.", "object_type": "post", "object_id": "post_123", "occurred_at": "2026-09-01T03:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^socialize:post:manual-publish-due:" } }, { "type": "socialize.post.publish_failed", "version": 1, "description": "Socialize recorded the durable post publish failed transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string" }, "campaign_name": { "type": "string" }, "window_start_date": { "type": "string", "format": "date-time" }, "window_end_date": { "type": "string", "format": "date-time" }, "platform": { "type": "string" }, "platform_post_id": { "type": [ "string", "null" ] }, "disconnect_event_id": { "type": "string" }, "requester_name": { "type": [ "string", "null" ] }, "requester_email": { "type": "string", "format": "email" }, "source_type": { "type": "string" }, "failure_code": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "title": "Post publishing failed", "body": "The publish failure was persisted and needs attention.", "object_type": "post", "object_id": "post_123", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^socialize:post:publish-failed:" } }, { "type": "socialize.post.published", "version": 1, "description": "Socialize recorded the durable post published transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string" }, "campaign_name": { "type": "string" }, "window_start_date": { "type": "string", "format": "date-time" }, "window_end_date": { "type": "string", "format": "date-time" }, "platform": { "type": "string" }, "platform_post_id": { "type": [ "string", "null" ] }, "disconnect_event_id": { "type": "string" }, "requester_name": { "type": [ "string", "null" ] }, "requester_email": { "type": "string", "format": "email" }, "source_type": { "type": "string" }, "failure_code": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "title": "Post published", "body": "The post reached its durable published state.", "object_type": "post", "object_id": "post_123", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^socialize:post:published:" } } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "dashboard:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "analytics.summary", "title": "Get analytics summary", "description": "Get social analytics summary.", "method": "GET", "path": "/api/analytics/summary", "permission": "analytics:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "startDate": { "type": "string", "minLength": 1 }, "endDate": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get analytics summary.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "days": 1, "startDate": "example", "endDate": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/analytics/summary", "body": null }, "effects": "Reads state through GET /api/analytics/summary without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/analytics/summary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "posts.list", "title": "List posts", "description": "List social posts.", "method": "GET", "path": "/api/posts", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "authorId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published", "failed", "cancelled", "archived" ] }, "platform": { "type": "string", "enum": [ "twitter", "x", "linkedin", "linkedin_company", "facebook", "instagram", "threads", "tiktok", "youtube" ] }, "campaignId": { "type": "string", "minLength": 1 }, "threadId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List posts.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "authorId": "example", "status": "draft", "platform": "twitter" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/posts", "body": null }, "effects": "Reads state through GET /api/posts without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/posts", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "posts.create", "title": "Create post", "description": "Create a social post.", "method": "POST", "path": "/api/posts", "permission": "posts:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 63206 }, "platform": { "type": "string", "enum": [ "twitter", "x", "linkedin", "linkedin_company", "facebook", "instagram", "threads", "tiktok", "youtube" ] }, "scheduledFor": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "publishNow": { "type": "boolean" }, "mediaUrl": { "type": "string", "format": "uri" }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif" ] }, "placement": { "type": "string", "enum": [ "feed", "story" ] }, "publishMode": { "type": "string", "enum": [ "auto", "manual" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "content", "platform" ], "additionalProperties": false }, "target": "api", "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "authorId": { "type": "string", "minLength": 1 }, "brandId": { "type": "string", "minLength": 1 }, "platform": { "type": "string" }, "status": { "type": "string" }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastPublishAttemptAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastPublishResultAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaThumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "content", "authorId", "brandId", "platform", "status", "scheduledFor", "publishedAt", "failedAt", "failureCode", "failureMessage", "lastPublishAttemptAt", "lastPublishResultAt", "mediaUrl", "mediaType", "mediaThumbnailUrl", "metadata", "createdAt", "updatedAt" ], "additionalProperties": false }, "destructive": false, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/applications/socialize#posts", "resource": { "kind": "brand", "idPath": "brandId" }, "effects": [ "Creates one draft or scheduled social post for the active brand." ], "errors": [ { "status": 403, "code": "forbidden", "recovery": "Select a brand bound to the credential and retry." } ], "verify": [ "Call posts.get with the returned id and confirm status, platform, and scheduledFor." ], "nextActionIds": [ "app_topolo_socialize.posts.get" ], "examples": [ { "title": "Schedule an X post", "description": "Use an ISO timestamp in the future for the active brand.", "input": { "content": "A concise launch update.", "platform": "twitter", "scheduledFor": "2026-08-01T09:00:00.000Z" } } ] }, "authorizationMode": "static", "documentation": { "example_input": { "content": "A concise launch update.", "platform": "twitter", "scheduledFor": "2026-08-01T09:00:00.000Z" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/posts", "body": { "content": "A concise launch update.", "platform": "twitter", "scheduledFor": "2026-08-01T09:00:00.000Z" } }, "effects": "Creates one draft or scheduled social post for the active brand.", "verification": [ "Call posts.get with the returned id and confirm status, platform, and scheduledFor." ], "recovery": [ "403 forbidden: Select a brand bound to the credential and retry." ], "docs_url": "https://docs.topolo.app/applications/socialize#posts", "resource": { "kind": "brand", "idPath": "brandId" }, "next_action_ids": [ "app_topolo_socialize.posts.get" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/posts", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "posts.get", "title": "Posts Get", "description": "Call GET /api/posts/{id}.", "method": "GET", "path": "/api/posts/{id}", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "authorId": { "type": "string", "minLength": 1 }, "brandId": { "type": "string", "minLength": 1 }, "platform": { "type": "string" }, "status": { "type": "string" }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastPublishAttemptAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastPublishResultAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaThumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "content", "authorId", "brandId", "platform", "status", "scheduledFor", "publishedAt", "failedAt", "failureCode", "failureMessage", "lastPublishAttemptAt", "lastPublishResultAt", "mediaUrl", "mediaType", "mediaThumbnailUrl", "metadata", "createdAt", "updatedAt" ], "additionalProperties": false }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/posts/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/posts/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/posts/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "posts.update", "title": "Posts Update", "description": "Call PUT /api/posts/{id}.", "method": "PUT", "path": "/api/posts/{id}", "permission": "posts:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1, "maxLength": 10000 }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published", "failed", "cancelled" ] }, "unschedule": { "type": "boolean" }, "platform": { "type": "string", "enum": [ "twitter", "x", "linkedin", "linkedin_company", "facebook", "instagram", "threads", "tiktok", "youtube" ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "mediaUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "placement": { "anyOf": [ { "type": "string", "enum": [ "feed", "story" ] }, { "type": "null" } ] }, "publishMode": { "anyOf": [ { "type": "string", "enum": [ "auto", "manual" ] }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Posts Update.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/posts/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/posts/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/posts/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "posts.delete", "title": "Posts Delete", "description": "Call DELETE /api/posts/{id}.", "method": "DELETE", "path": "/api/posts/{id}", "permission": "posts:write", "readOnly": false, "destructive": true, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Posts Delete.", "additionalProperties": true }, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/posts/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/posts/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/posts/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "posts.publish", "title": "Posts Publish", "description": "Call POST /api/posts/{id}/publish.", "method": "POST", "path": "/api/posts/{id}/publish", "permission": "posts:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Posts Publish.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/posts/00000000-0000-4000-8000-000000000000/publish", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/posts/{id}/publish. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/posts/*/publish", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.list", "title": "List campaigns", "description": "List social campaigns.", "method": "GET", "path": "/api/campaigns", "permission": "calendar:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdBy": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "scheduled", "active", "completed", "cancelled" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List campaigns.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "createdBy": "example", "status": "draft", "limit": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/campaigns", "body": null }, "effects": "Reads state through GET /api/campaigns without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/campaigns", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.create", "title": "Create campaign", "description": "Create a social campaign.", "method": "POST", "path": "/api/campaigns", "permission": "calendar:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 1000 }, "platforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "twitter", "linkedin", "facebook", "instagram", "tiktok", "threads", "youtube" ] } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 100 }, "postId": { "type": "string", "minLength": 1 }, "content": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 63206 }, "mediaUrls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "media": { "type": "array", "items": { "type": "string" } }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "text" ], "additionalProperties": false }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "weight" ], "additionalProperties": false } }, "goals": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "windowStartDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "windowEndDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "timezone": { "type": "string" }, "scheduleDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] } }, "scheduleTimes": { "type": "array", "items": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" } }, "status": { "type": "string", "enum": [ "draft", "scheduled" ] } }, "required": [ "name", "platforms" ], "additionalProperties": false }, "target": "api", "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "brandId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "createdBy": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "goals": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "enabled": { "type": "boolean" }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "platform", "enabled", "settings" ], "additionalProperties": false } }, "timezone": { "type": "string" }, "scheduleDays": { "type": "array", "items": { "type": "string" } }, "scheduleTimes": { "type": "array", "items": { "type": "string" } }, "windowStartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "windowEndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paused": { "type": "boolean" }, "pausedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resumedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "weight": { "type": "number" }, "postId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "weight", "postId" ], "additionalProperties": false } }, "scheduledPosts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "platform": { "type": "string" }, "scheduledFor": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "platform", "scheduledFor", "status" ], "additionalProperties": false } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "createdBy", "status", "windowStartDate", "windowEndDate", "paused", "pausedAt", "resumedAt", "variants", "createdAt", "updatedAt" ], "additionalProperties": false }, "destructive": false, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/applications/socialize#campaigns", "resource": { "kind": "brand", "idPath": "brandId" }, "effects": [ "Creates campaign variants for the active brand.", "When status=scheduled, materializes one durable post per cadence slot and enabled platform." ], "errors": [ { "status": 400, "code": "validation_error", "recovery": "Correct platform, variant weights, window, timezone, days, and times." } ], "verify": [ "Call campaigns.get and posts.list with campaignId; scheduled campaigns must return concrete scheduled posts." ], "nextActionIds": [ "app_topolo_socialize.campaigns.get", "app_topolo_socialize.posts.list" ], "examples": [ { "title": "Create and schedule a launch campaign", "description": "Materialize weekday posts at 09:00 in the campaign timezone.", "input": { "name": "Launch campaign", "status": "scheduled", "platforms": [ "twitter", "linkedin" ], "variants": [ { "name": "Primary", "weight": 100, "content": { "text": "Launch update" } } ], "windowStartDate": "2026-08-01T00:00:00.000Z", "windowEndDate": "2026-08-08T23:59:59.000Z", "timezone": "Asia/Dubai", "scheduleDays": [ "monday", "wednesday", "friday" ], "scheduleTimes": [ "09:00" ] } } ] }, "authorizationMode": "static", "documentation": { "example_input": { "name": "Launch campaign", "status": "scheduled", "platforms": [ "twitter", "linkedin" ], "variants": [ { "name": "Primary", "weight": 100, "content": { "text": "Launch update" } } ], "windowStartDate": "2026-08-01T00:00:00.000Z", "windowEndDate": "2026-08-08T23:59:59.000Z", "timezone": "Asia/Dubai", "scheduleDays": [ "monday", "wednesday", "friday" ], "scheduleTimes": [ "09:00" ] }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/campaigns", "body": { "name": "Launch campaign", "status": "scheduled", "platforms": [ "twitter", "linkedin" ], "variants": [ { "name": "Primary", "weight": 100, "content": { "text": "Launch update" } } ], "windowStartDate": "2026-08-01T00:00:00.000Z", "windowEndDate": "2026-08-08T23:59:59.000Z", "timezone": "Asia/Dubai", "scheduleDays": [ "monday", "wednesday", "friday" ], "scheduleTimes": [ "09:00" ] } }, "effects": "Creates campaign variants for the active brand. When status=scheduled, materializes one durable post per cadence slot and enabled platform.", "verification": [ "Call campaigns.get and posts.list with campaignId; scheduled campaigns must return concrete scheduled posts." ], "recovery": [ "400 validation_error: Correct platform, variant weights, window, timezone, days, and times." ], "docs_url": "https://docs.topolo.app/applications/socialize#campaigns", "resource": { "kind": "brand", "idPath": "brandId" }, "next_action_ids": [ "app_topolo_socialize.campaigns.get", "app_topolo_socialize.posts.list" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/campaigns", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.schedule", "title": "Campaigns Schedule", "description": "Call POST /api/campaigns/{id}/schedule.", "method": "POST", "path": "/api/campaigns/{id}/schedule", "permission": "calendar:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "windowStartDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "windowEndDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "windowStartDate", "windowEndDate" ], "additionalProperties": false }, "target": "api", "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "brandId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "createdBy": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "goals": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "enabled": { "type": "boolean" }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "platform", "enabled", "settings" ], "additionalProperties": false } }, "timezone": { "type": "string" }, "scheduleDays": { "type": "array", "items": { "type": "string" } }, "scheduleTimes": { "type": "array", "items": { "type": "string" } }, "windowStartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "windowEndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paused": { "type": "boolean" }, "pausedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resumedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "weight": { "type": "number" }, "postId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "weight", "postId" ], "additionalProperties": false } }, "scheduledPosts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "platform": { "type": "string" }, "scheduledFor": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "platform", "scheduledFor", "status" ], "additionalProperties": false } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "createdBy", "status", "windowStartDate", "windowEndDate", "paused", "pausedAt", "resumedAt", "variants", "createdAt", "updatedAt" ], "additionalProperties": false }, "destructive": false, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/applications/socialize#campaigns", "resource": { "kind": "campaign", "idPath": "id" }, "effects": [ "Transitions a draft campaign to scheduled and idempotently materializes its publish occurrences." ], "errors": [ { "status": 400, "code": "validation_error", "recovery": "Ensure the campaign has content variants, enabled platforms, and cadence slots inside the window." }, { "status": 403, "code": "forbidden", "recovery": "Use a campaign owned by the credential-bound brand." } ], "verify": [ "Confirm scheduledPosts is non-empty and call posts.list with campaignId." ], "nextActionIds": [ "app_topolo_socialize.posts.list", "app_topolo_socialize.brands.publishing_readiness.get" ], "examples": [ { "title": "Schedule a prepared campaign", "description": "Use the campaign id returned by campaigns.create.", "input": { "id": "campaign_example", "windowStartDate": "2026-08-01T00:00:00.000Z", "windowEndDate": "2026-08-08T23:59:59.000Z" } } ] }, "authorizationMode": "static", "documentation": { "example_input": { "id": "campaign_example", "windowStartDate": "2026-08-01T00:00:00.000Z", "windowEndDate": "2026-08-08T23:59:59.000Z" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/campaigns/campaign_example/schedule", "body": { "id": "campaign_example", "windowStartDate": "2026-08-01T00:00:00.000Z", "windowEndDate": "2026-08-08T23:59:59.000Z" } }, "effects": "Transitions a draft campaign to scheduled and idempotently materializes its publish occurrences.", "verification": [ "Confirm scheduledPosts is non-empty and call posts.list with campaignId." ], "recovery": [ "400 validation_error: Ensure the campaign has content variants, enabled platforms, and cadence slots inside the window.", "403 forbidden: Use a campaign owned by the credential-bound brand." ], "docs_url": "https://docs.topolo.app/applications/socialize#campaigns", "resource": { "kind": "campaign", "idPath": "id" }, "next_action_ids": [ "app_topolo_socialize.posts.list", "app_topolo_socialize.brands.publishing_readiness.get" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/campaigns/*/schedule", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.list", "title": "List brands", "description": "List social brands/accounts.", "method": "GET", "path": "/api/brands", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List brands.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brands", "body": null }, "effects": "Reads state through GET /api/brands without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brands", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.create", "title": "Create brand", "description": "Create a social brand/account.", "method": "POST", "path": "/api/brands", "permission": "workspace:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "isDefault": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "logoUrl": { "type": "string" }, "memberCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organizationId": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "description", "logoUrl", "memberCount", "organizationId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/platform/workspaces/", "resource": { "kind": "workspace", "idPath": "data.id" }, "effects": [ "Creates canonical workspace identity in Topolo Auth for Socialize.", "Creates the Socialize-owned brand profile mirror for that workspace." ], "errors": [ { "status": 403, "code": "forbidden", "recovery": "Confirm the caller has workspace:write for Socialize and the organization can create another workspace." }, { "status": 409, "code": "workspace_creation_conflict", "recovery": "List Socialize brands before retrying so a successful creation is not duplicated." } ], "verify": [ "Call brands.list and confirm the returned workspace id appears exactly once." ], "nextActionIds": [ "app_topolo_socialize.brands.list" ], "rollbackActionId": "app_topolo_socialize.workspaces.delete", "examples": [ { "title": "Create a founder brand", "description": "Auth generates the stable workspace slug; Socialize stores only its app-owned profile.", "input": { "name": "Ashley Lane - Topolo Founder", "description": "Founder-led social presence for Topolo." } } ] }, "documentation": { "example_input": { "name": "Ashley Lane - Topolo Founder", "description": "Founder-led social presence for Topolo." }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brands", "body": { "name": "Ashley Lane - Topolo Founder", "description": "Founder-led social presence for Topolo." } }, "effects": "Creates canonical workspace identity in Topolo Auth for Socialize. Creates the Socialize-owned brand profile mirror for that workspace.", "verification": [ "Call brands.list and confirm the returned workspace id appears exactly once." ], "recovery": [ "403 forbidden: Confirm the caller has workspace:write for Socialize and the organization can create another workspace.", "409 workspace_creation_conflict: List Socialize brands before retrying so a successful creation is not duplicated." ], "docs_url": "https://docs.topolo.app/platform/workspaces/", "resource": { "kind": "workspace", "idPath": "data.id" }, "next_action_ids": [ "app_topolo_socialize.brands.list" ], "rollback_action_id": "app_topolo_socialize.workspaces.delete" }, "implementation": { "status": "implemented", "route_key": "POST /api/brands", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "Delete workspace", "description": "Delete an empty non-default Socialize workspace.", "method": "DELETE", "path": "/api/workspaces/{id}", "permission": "workspace:delete", "authorizationMode": "static", "readOnly": false, "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", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/workspaces/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/workspaces/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.get", "title": "Get brand", "description": "Get a brand by id.", "method": "GET", "path": "/api/brands/{id}", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brands/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/brands/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brands/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.generate_content", "title": "Generate content", "description": "Generate social content with AI.", "method": "POST", "path": "/api/ai/generate-content", "permission": "posts:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "prompt": { "type": "string", "minLength": 10, "maxLength": 10000 }, "contentTypeId": { "type": "string", "minLength": 1 }, "maxTokens": { "type": "number", "minimum": 100, "maximum": 4000 }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "channel": { "type": "string", "enum": [ "twitter", "x", "linkedin", "linkedin_company", "facebook", "instagram", "threads", "tiktok", "youtube" ] }, "audience": { "type": "string", "maxLength": 500 }, "objective": { "type": "string", "maxLength": 500 }, "claimIds": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1 } }, "ctaId": { "type": "string", "minLength": 1 } }, "required": [ "prompt" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Generate content.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "prompt": "examplexxx" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/generate-content", "body": { "prompt": "examplexxx" } }, "effects": "May change state through POST /api/ai/generate-content. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/generate-content", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "posts.archive", "title": "Archive post", "description": "Archive a Socialize post.", "method": "POST", "path": "/api/posts/{id}/archive", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Archive post.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/posts/00000000-0000-4000-8000-000000000000/archive", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/posts/{id}/archive. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/posts/*/archive", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "posts.reschedule", "title": "Reschedule post", "description": "Reschedule a Socialize post.", "method": "PATCH", "path": "/api/posts/{id}/reschedule", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "scheduledFor": { "type": "string", "minLength": 1 } }, "required": [ "id", "scheduledFor" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Reschedule post.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "scheduledFor": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/posts/00000000-0000-4000-8000-000000000000/reschedule", "body": { "id": "00000000-0000-4000-8000-000000000000", "scheduledFor": "example" } }, "effects": "May change state through PATCH /api/posts/{id}/reschedule. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/posts/*/reschedule", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "posts.toggle_pause", "title": "Toggle post pause", "description": "Toggle pause on a Socialize post.", "method": "PATCH", "path": "/api/posts/{id}/toggle-pause", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "paused": { "type": "boolean" } }, "required": [ "id", "paused" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Toggle post pause.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "paused": true }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/posts/00000000-0000-4000-8000-000000000000/toggle-pause", "body": { "id": "00000000-0000-4000-8000-000000000000", "paused": true } }, "effects": "May change state through PATCH /api/posts/{id}/toggle-pause. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/posts/*/toggle-pause", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_ops.queue.get", "title": "Get content ops queue", "description": "Get the Socialize content ops queue.", "method": "GET", "path": "/api/content-ops/queue", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channel": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "approval_state": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get content ops queue.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "channel": "example", "status": "example", "approval_state": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/content-ops/queue", "body": null }, "effects": "Reads state through GET /api/content-ops/queue without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/content-ops/queue", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_ops.daily.get", "title": "Get daily content ops", "description": "Get Socialize daily content ops summary.", "method": "GET", "path": "/api/content-ops/daily", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "date": { "type": "string", "minLength": 1 }, "utc_offset": { "type": "string", "minLength": 1 }, "queue_limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get daily content ops.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "date": "example", "utc_offset": "example", "queue_limit": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/content-ops/daily", "body": null }, "effects": "Reads state through GET /api/content-ops/daily without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/content-ops/daily", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_ops.events.list", "title": "List content ops events", "description": "List Socialize content ops events.", "method": "GET", "path": "/api/content-ops/events", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "date": { "type": "string", "minLength": 1 }, "utc_offset": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List content ops events.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "date": "example", "utc_offset": "example", "limit": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/content-ops/events", "body": null }, "effects": "Reads state through GET /api/content-ops/events without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/content-ops/events", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_ops.deck.get", "title": "Get content ops deck", "description": "Get the Socialize content ops deck.", "method": "GET", "path": "/api/content-ops/deck", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "platform": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get content ops deck.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "platform": "example", "limit": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/content-ops/deck", "body": null }, "effects": "Reads state through GET /api/content-ops/deck without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/content-ops/deck", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_ops.items.get", "title": "Get content ops item", "description": "Get a Socialize content ops item.", "method": "GET", "path": "/api/content-ops/items/{id}", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get content ops item.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/content-ops/items/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/content-ops/items/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/content-ops/items/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_ops.items.update", "title": "Update content ops item", "description": "Update a Socialize content ops item.", "method": "PATCH", "path": "/api/content-ops/items/{id}", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 } }, "required": [ "id", "content" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update content ops item.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "content": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/content-ops/items/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000", "content": "example" } }, "effects": "May change state through PATCH /api/content-ops/items/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/content-ops/items/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_ops.items.approve", "title": "Approve content ops item", "description": "Approve a Socialize content ops item.", "method": "POST", "path": "/api/content-ops/items/{id}/approve", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Approve content ops item.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/content-ops/items/00000000-0000-4000-8000-000000000000/approve", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/content-ops/items/{id}/approve. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/content-ops/items/*/approve", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_ops.items.reject", "title": "Reject content ops item", "description": "Reject a Socialize content ops item.", "method": "POST", "path": "/api/content-ops/items/{id}/reject", "permission": "posts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Reject content ops item.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/content-ops/items/00000000-0000-4000-8000-000000000000/reject", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/content-ops/items/{id}/reject. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/content-ops/items/*/reject", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_ops.items.reschedule", "title": "Reschedule content ops item", "description": "Reschedule a Socialize content ops item.", "method": "POST", "path": "/api/content-ops/items/{id}/reschedule", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "scheduled_at": { "type": "string", "minLength": 1 } }, "required": [ "id", "scheduled_at" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Reschedule content ops item.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "scheduled_at": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/content-ops/items/00000000-0000-4000-8000-000000000000/reschedule", "body": { "id": "00000000-0000-4000-8000-000000000000", "scheduled_at": "example" } }, "effects": "May change state through POST /api/content-ops/items/{id}/reschedule. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/content-ops/items/*/reschedule", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_ops.items.retry", "title": "Retry content ops item", "description": "Retry a Socialize content ops item.", "method": "POST", "path": "/api/content-ops/items/{id}/retry", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Retry content ops item.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/content-ops/items/00000000-0000-4000-8000-000000000000/retry", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/content-ops/items/{id}/retry. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/content-ops/items/*/retry", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.get", "title": "Get campaign", "description": "Get a Socialize campaign.", "method": "GET", "path": "/api/campaigns/{id}", "permission": "calendar:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "brandId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "createdBy": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "goals": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "enabled": { "type": "boolean" }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "platform", "enabled", "settings" ], "additionalProperties": false } }, "timezone": { "type": "string" }, "scheduleDays": { "type": "array", "items": { "type": "string" } }, "scheduleTimes": { "type": "array", "items": { "type": "string" } }, "windowStartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "windowEndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paused": { "type": "boolean" }, "pausedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resumedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "weight": { "type": "number" }, "postId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "weight", "postId" ], "additionalProperties": false } }, "scheduledPosts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "platform": { "type": "string" }, "scheduledFor": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "platform", "scheduledFor", "status" ], "additionalProperties": false } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "createdBy", "status", "windowStartDate", "windowEndDate", "paused", "pausedAt", "resumedAt", "variants", "createdAt", "updatedAt" ], "additionalProperties": false }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/campaigns/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/campaigns/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/campaigns/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.update", "title": "Update campaign", "description": "Update a Socialize campaign.", "method": "PUT", "path": "/api/campaigns/{id}", "permission": "calendar:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string" }, "status": { "type": "string" }, "goals": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "enabled": { "type": "boolean" }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "platform", "enabled", "settings" ], "additionalProperties": false } }, "windowStartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "windowEndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "type": "string" }, "scheduleDays": { "type": "array", "items": { "type": "string" } }, "scheduleTimes": { "type": "array", "items": { "type": "string" } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 100 }, "postId": { "type": "string", "minLength": 1 }, "content": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 63206 }, "mediaUrls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "media": { "type": "array", "items": { "type": "string" } }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "text" ], "additionalProperties": false }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "weight" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update campaign.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/campaigns/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/campaigns/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/campaigns/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.delete", "title": "Delete campaign", "description": "Delete a Socialize campaign.", "method": "DELETE", "path": "/api/campaigns/{id}", "permission": "calendar:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete campaign.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/campaigns/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/campaigns/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/campaigns/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.activate", "title": "Activate campaign", "description": "Activate a Socialize campaign.", "method": "POST", "path": "/api/campaigns/{id}/activate", "permission": "calendar:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Activate campaign.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/campaigns/00000000-0000-4000-8000-000000000000/activate", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/campaigns/{id}/activate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/campaigns/*/activate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.complete", "title": "Complete campaign", "description": "Complete a Socialize campaign.", "method": "POST", "path": "/api/campaigns/{id}/complete", "permission": "calendar:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Complete campaign.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/campaigns/00000000-0000-4000-8000-000000000000/complete", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/campaigns/{id}/complete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/campaigns/*/complete", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.cancel", "title": "Cancel campaign", "description": "Cancel a Socialize campaign.", "method": "POST", "path": "/api/campaigns/{id}/cancel", "permission": "calendar:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Cancel campaign.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/campaigns/00000000-0000-4000-8000-000000000000/cancel", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/campaigns/{id}/cancel. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/campaigns/*/cancel", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.pause", "title": "Pause campaign", "description": "Pause a Socialize campaign.", "method": "POST", "path": "/api/campaigns/{id}/pause", "permission": "calendar:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Pause campaign.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/campaigns/00000000-0000-4000-8000-000000000000/pause", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/campaigns/{id}/pause. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/campaigns/*/pause", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.resume", "title": "Resume campaign", "description": "Resume a Socialize campaign.", "method": "POST", "path": "/api/campaigns/{id}/resume", "permission": "calendar:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Resume campaign.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/campaigns/00000000-0000-4000-8000-000000000000/resume", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/campaigns/{id}/resume. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/campaigns/*/resume", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.analytics.get", "title": "Get campaign analytics", "description": "Get Socialize campaign analytics.", "method": "GET", "path": "/api/campaigns/{id}/analytics", "permission": "analytics:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "days": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "startDate": { "type": "string", "minLength": 1 }, "endDate": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get campaign analytics.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/campaigns/00000000-0000-4000-8000-000000000000/analytics", "body": null }, "effects": "Reads state through GET /api/campaigns/{id}/analytics without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/campaigns/*/analytics", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.analytics_engine.get", "title": "Get campaign analytics engine", "description": "Get Socialize campaign analytics engine data.", "method": "GET", "path": "/api/campaigns/{id}/analytics/engine", "permission": "analytics:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "days": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "startDate": { "type": "string", "minLength": 1 }, "endDate": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get campaign analytics engine.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/campaigns/00000000-0000-4000-8000-000000000000/analytics/engine", "body": null }, "effects": "Reads state through GET /api/campaigns/{id}/analytics/engine without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/campaigns/*/analytics/engine", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.variants.analytics.get", "title": "Get campaign variant analytics", "description": "Get Socialize campaign variant analytics.", "method": "GET", "path": "/api/campaigns/{id}/analytics/variants/{variantId}", "permission": "analytics:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "variantId": { "type": "string", "minLength": 1 }, "days": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "startDate": { "type": "string", "minLength": 1 }, "endDate": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "minLength": 1 } }, "required": [ "id", "variantId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get campaign variant analytics.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "variantId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/campaigns/00000000-0000-4000-8000-000000000000/analytics/variants/example", "body": null }, "effects": "Reads state through GET /api/campaigns/{id}/analytics/variants/{variantId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/campaigns/*/analytics/variants/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "scheduler.process", "title": "Process scheduler", "description": "Process Socialize scheduled posts.", "method": "POST", "path": "/api/scheduler/process", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Process scheduler.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/scheduler/process", "body": {} }, "effects": "May change state through POST /api/scheduler/process. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/scheduler/process", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "scheduler.status.get", "title": "Get scheduler status", "description": "Get Socialize scheduler status.", "method": "GET", "path": "/api/scheduler/status", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get scheduler status.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/scheduler/status", "body": null }, "effects": "Reads state through GET /api/scheduler/status without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/scheduler/status", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "scheduler.drafts.from_trend", "title": "Create draft from trend", "description": "Create a Socialize scheduler draft from a trend.", "method": "POST", "path": "/api/scheduler/drafts/from-trend", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "trendId": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "enum": [ "linkedin", "x", "instagram", "tiktok", "youtube" ] }, "content": { "type": "string", "minLength": 1 }, "hashtags": { "type": "array", "items": { "type": "string" } }, "scheduledFor": { "type": "string", "minLength": 1 } }, "required": [ "trendId", "platform", "content" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create draft from trend.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "trendId": "example", "platform": "linkedin", "content": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/scheduler/drafts/from-trend", "body": { "trendId": "example", "platform": "linkedin", "content": "example" } }, "effects": "May change state through POST /api/scheduler/drafts/from-trend. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/scheduler/drafts/from-trend", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.upload_url.create", "title": "Create media upload URL", "description": "Create a Socialize media upload URL.", "method": "POST", "path": "/api/media/upload", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "minLength": 1 }, "size": { "type": "number", "exclusiveMinimum": 0, "maximum": 524288000 }, "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "key": { "type": "string", "minLength": 1 } }, "required": [ "filename", "contentType", "size" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create media upload URL.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "upload": { "profile": "url-session", "fileNameField": "filename", "contentTypeField": "contentType", "sizeField": "size", "maxBytes": 524288000, "acceptedContentTypes": [ "image/jpeg", "image/png", "image/gif", "image/webp", "video/mp4", "video/webm", "video/quicktime" ], "uploadUrlPath": "uploadUrl", "uploadMethod": "PUT", "complete": { "actionId": "app_topolo_socialize.media.upload.complete", "inputField": "id", "responsePath": "mediaId" } } }, "documentation": { "example_input": { "filename": "example", "contentType": "example", "size": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/media/upload", "body": { "filename": "example", "contentType": "example", "size": 1 } }, "effects": "May change state through POST /api/media/upload. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/media/upload", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.list", "title": "List media", "description": "List Socialize media.", "method": "GET", "path": "/api/media/list", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string", "minLength": 1 }, "collection": { "type": "string", "minLength": 1 }, "tag": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "all", "image", "video", "audio", "document" ] }, "sort": { "type": "string", "enum": [ "date", "name", "size", "type" ] }, "order": { "type": "string", "enum": [ "asc", "desc" ] }, "status": { "type": "string", "enum": [ "active", "archived", "deleted" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List media.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "search": "example", "collection": "example", "tag": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/media/list", "body": null }, "effects": "Reads state through GET /api/media/list without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/media/list", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.bulk", "title": "Run bulk media operation", "description": "Run a Socialize bulk media operation.", "method": "POST", "path": "/api/media/bulk", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mediaIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "action": { "type": "string", "enum": [ "delete", "archive", "restore", "tag", "move" ] }, "tagId": { "type": "string", "minLength": 1 }, "collectionId": { "type": "string", "minLength": 1 } }, "required": [ "mediaIds", "action" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Run bulk media operation.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "mediaIds": [ "example" ], "action": "delete" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/media/bulk", "body": { "mediaIds": [ "example" ], "action": "delete" } }, "effects": "May change state through POST /api/media/bulk. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/media/bulk", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.tags.list", "title": "List media tags", "description": "List Socialize media tags.", "method": "GET", "path": "/api/media/tags", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List media tags.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/media/tags", "body": null }, "effects": "Reads state through GET /api/media/tags without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/media/tags", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.tags.create", "title": "Create media tag", "description": "Create a Socialize media tag.", "method": "POST", "path": "/api/media/tags", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "required": [ "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create media tag.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "name": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/media/tags", "body": { "name": "example" } }, "effects": "May change state through POST /api/media/tags. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/media/tags", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.tags.delete", "title": "Delete media tag", "description": "Delete a Socialize media tag.", "method": "DELETE", "path": "/api/media/tags/{id}", "permission": "posts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete media tag.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/media/tags/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/media/tags/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/media/tags/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.collections.list", "title": "List media collections", "description": "List Socialize media collections.", "method": "GET", "path": "/api/media/collections", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List media collections.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/media/collections", "body": null }, "effects": "Reads state through GET /api/media/collections without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/media/collections", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.collections.create", "title": "Create media collection", "description": "Create a Socialize media collection.", "method": "POST", "path": "/api/media/collections", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "parentId": { "type": "string", "minLength": 1 } }, "required": [ "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create media collection.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "name": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/media/collections", "body": { "name": "example" } }, "effects": "May change state through POST /api/media/collections. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/media/collections", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.collections.delete", "title": "Delete media collection", "description": "Delete a Socialize media collection.", "method": "DELETE", "path": "/api/media/collections/{id}", "permission": "posts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete media collection.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/media/collections/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/media/collections/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/media/collections/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.metadata.get", "title": "Get media metadata", "description": "Get Socialize media metadata.", "method": "GET", "path": "/api/media/{id}/metadata", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get media metadata.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/media/00000000-0000-4000-8000-000000000000/metadata", "body": null }, "effects": "Reads state through GET /api/media/{id}/metadata without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/media/*/metadata", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.upload.complete", "title": "Complete media upload", "description": "Complete a Socialize media upload.", "method": "POST", "path": "/api/media/{id}/complete", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Complete media upload.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/media/00000000-0000-4000-8000-000000000000/complete", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/media/{id}/complete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/media/*/complete", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.metadata.bulk_get", "title": "Bulk get media metadata", "description": "Bulk get Socialize media metadata.", "method": "POST", "path": "/api/media/metadata", "permission": "posts:read", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mediaIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "mediaIds" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Bulk get media metadata.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "mediaIds": [ "example" ] }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/media/metadata", "body": { "mediaIds": [ "example" ] } }, "effects": "May change state through POST /api/media/metadata. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/media/metadata", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "flags.list", "title": "List flags", "description": "List Socialize flags.", "method": "GET", "path": "/api/flags", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List flags.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/flags", "body": null }, "effects": "Reads state through GET /api/flags without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/flags", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "flags.create", "title": "Create flag", "description": "Create a Socialize flag.", "method": "POST", "path": "/api/flags", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "rolloutPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "targetRoles": { "type": "array", "items": { "type": "string" } }, "targetEmails": { "type": "array", "items": { "type": "string" } }, "environments": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "description" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create flag.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "name": "example", "description": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/flags", "body": { "name": "example", "description": "example" } }, "effects": "May change state through POST /api/flags. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/flags", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "flags.me.list", "title": "List my flags", "description": "List current-user Socialize flags.", "method": "GET", "path": "/api/flags/me", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List my flags.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/flags/me", "body": null }, "effects": "Reads state through GET /api/flags/me without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/flags/me", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "flags.user.list", "title": "List user flags", "description": "List Socialize flags for a user.", "method": "GET", "path": "/api/flags/user/{id}", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List user flags.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/flags/user/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/flags/user/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/flags/user/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "flags.user.set", "title": "Set user flag", "description": "Set a Socialize flag for a user.", "method": "PUT", "path": "/api/flags/{flagId}/users/{userId}", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "flagId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" } }, "required": [ "flagId", "userId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Set user flag.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "flagId": "example", "userId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/flags/example/users/example", "body": { "flagId": "example", "userId": "example" } }, "effects": "May change state through PUT /api/flags/{flagId}/users/{userId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/flags/*/users/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "flags.user.remove", "title": "Remove user flag", "description": "Remove a Socialize flag for a user.", "method": "DELETE", "path": "/api/flags/{flagId}/users/{userId}", "permission": "accounts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "flagId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 } }, "required": [ "flagId", "userId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Remove user flag.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "flagId": "example", "userId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/flags/example/users/example", "body": null }, "effects": "May change state through DELETE /api/flags/{flagId}/users/{userId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/flags/*/users/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "flags.get", "title": "Get flag", "description": "Get a Socialize flag.", "method": "GET", "path": "/api/flags/{id}", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get flag.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/flags/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/flags/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/flags/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "flags.update", "title": "Update flag", "description": "Update a Socialize flag.", "method": "PATCH", "path": "/api/flags/{id}", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "rolloutPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "targetRoles": { "type": "array", "items": { "type": "string" } }, "targetEmails": { "type": "array", "items": { "type": "string" } }, "environments": { "type": "array", "items": { "type": "string" } } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update flag.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/flags/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PATCH /api/flags/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/flags/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "flags.delete", "title": "Delete flag", "description": "Delete a Socialize flag.", "method": "DELETE", "path": "/api/flags/{id}", "permission": "accounts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete flag.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/flags/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/flags/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/flags/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organization.create", "title": "Create organization brand", "description": "Create a Socialize organization brand.", "method": "POST", "path": "/api/organization", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "isDefault": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create organization brand.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "name": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/organization", "body": { "name": "example" } }, "effects": "May change state through POST /api/organization. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/organization", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organization.get", "title": "Get organization brand", "description": "Get the Socialize organization brand.", "method": "GET", "path": "/api/organization", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get organization brand.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organization", "body": null }, "effects": "Reads state through GET /api/organization without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organization", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organization.accept_invite", "title": "Accept organization invite", "description": "Accept a Socialize organization invite.", "method": "POST", "path": "/api/organization/accept-invite", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "token": { "type": "string", "minLength": 10, "maxLength": 100 } }, "required": [ "token" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Accept organization invite.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "token": "examplexxx" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/organization/accept-invite", "body": { "token": "examplexxx" } }, "effects": "May change state through POST /api/organization/accept-invite. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/organization/accept-invite", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.update", "title": "Update brand", "description": "Update a Socialize brand.", "method": "PUT", "path": "/api/brands/{id}", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "logoUrl": { "type": "string", "format": "uri" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update brand.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/brands/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/brands/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/brands/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.transfer_organization", "title": "Transfer brand organization", "description": "Transfer a Socialize brand organization.", "method": "POST", "path": "/api/brands/{id}/transfer-organization", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "targetOrganizationId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "id", "targetOrganizationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Transfer brand organization.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "targetOrganizationId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brands/00000000-0000-4000-8000-000000000000/transfer-organization", "body": { "id": "00000000-0000-4000-8000-000000000000", "targetOrganizationId": "example" } }, "effects": "May change state through POST /api/brands/{id}/transfer-organization. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brands/*/transfer-organization", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.members.list", "title": "List brand members", "description": "List Socialize brand members.", "method": "GET", "path": "/api/brands/{id}/members", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List brand members.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brands/00000000-0000-4000-8000-000000000000/members", "body": null }, "effects": "Reads state through GET /api/brands/{id}/members without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brands/*/members", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.join_requests.list", "title": "List brand join requests", "description": "List Socialize brand join requests.", "method": "GET", "path": "/api/brands/{id}/join-requests", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List brand join requests.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brands/00000000-0000-4000-8000-000000000000/join-requests", "body": null }, "effects": "Reads state through GET /api/brands/{id}/join-requests without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brands/*/join-requests", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "join_requests.approve", "title": "Approve join request", "description": "Approve a Socialize join request.", "method": "PUT", "path": "/api/join-requests/{id}", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Approve join request.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/join-requests/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/join-requests/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/join-requests/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "join_requests.reject", "title": "Reject join request", "description": "Reject a Socialize join request.", "method": "DELETE", "path": "/api/join-requests/{id}", "permission": "accounts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Reject join request.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/join-requests/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/join-requests/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/join-requests/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.get", "title": "Get organization", "description": "Get a Socialize organization.", "method": "GET", "path": "/api/organizations/{id}", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get organization.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/organizations/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "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.update", "title": "Update organization", "description": "Update a Socialize organization.", "method": "PUT", "path": "/api/organizations/{id}", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "logoUrl": { "type": "string", "format": "uri" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update organization.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/organizations/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/organizations/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/organizations/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.members.list", "title": "List organization members", "description": "List Socialize organization members.", "method": "GET", "path": "/api/organizations/{id}/members", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List organization members.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/00000000-0000-4000-8000-000000000000/members", "body": null }, "effects": "Reads state through GET /api/organizations/{id}/members without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/*/members", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.members.invite", "title": "Invite organization member", "description": "Invite a Socialize organization member.", "method": "POST", "path": "/api/organizations/{id}/members", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "email": { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 30 } }, "required": [ "id", "email", "role" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Invite organization member.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "email": "user@example.com", "role": "admin" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/organizations/00000000-0000-4000-8000-000000000000/members", "body": { "id": "00000000-0000-4000-8000-000000000000", "email": "user@example.com", "role": "admin" } }, "effects": "May change state through POST /api/organizations/{id}/members. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/organizations/*/members", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.members.remove", "title": "Remove organization member", "description": "Remove a Socialize organization member.", "method": "DELETE", "path": "/api/organizations/{id}/members/{userId}", "permission": "accounts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 } }, "required": [ "id", "userId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Remove organization member.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "userId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/00000000-0000-4000-8000-000000000000/members/example", "body": null }, "effects": "May change state through DELETE /api/organizations/{id}/members/{userId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/*/members/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.members.update_role", "title": "Update organization member role", "description": "Update a Socialize organization member role.", "method": "PUT", "path": "/api/organizations/{id}/members/{userId}", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] } }, "required": [ "id", "userId", "role" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update organization member role.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "userId": "example", "role": "admin" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/organizations/00000000-0000-4000-8000-000000000000/members/example", "body": { "id": "00000000-0000-4000-8000-000000000000", "userId": "example", "role": "admin" } }, "effects": "May change state through PUT /api/organizations/{id}/members/{userId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/organizations/*/members/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.invites.list", "title": "List organization invites", "description": "List Socialize organization invites.", "method": "GET", "path": "/api/organizations/{id}/invites", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List organization invites.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/00000000-0000-4000-8000-000000000000/invites", "body": null }, "effects": "Reads state through GET /api/organizations/{id}/invites without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/*/invites", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.invites.cancel", "title": "Cancel organization invite", "description": "Cancel a Socialize organization invite.", "method": "DELETE", "path": "/api/organizations/{id}/invites/{inviteId}", "permission": "accounts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "inviteId": { "type": "string", "minLength": 1 } }, "required": [ "id", "inviteId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Cancel organization invite.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "inviteId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/00000000-0000-4000-8000-000000000000/invites/example", "body": null }, "effects": "May change state through DELETE /api/organizations/{id}/invites/{inviteId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/*/invites/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.activity.list", "title": "List organization activity", "description": "List Socialize organization activity.", "method": "GET", "path": "/api/organizations/{id}/activity", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List organization activity.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/00000000-0000-4000-8000-000000000000/activity", "body": null }, "effects": "Reads state through GET /api/organizations/{id}/activity without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/*/activity", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.export", "title": "Export organization data", "description": "Export organization-authored Socialize data without provider credentials or media binaries.", "method": "GET", "path": "/api/organizations/{id}/data", "permission": "privacy:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/00000000-0000-4000-8000-000000000000/data", "body": null }, "effects": "Reads state through GET /api/organizations/{id}/data without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.erase", "title": "Erase organization data", "description": "Erase organization-authored Socialize data, provider connections, and media objects after active publishing work is cleared.", "method": "DELETE", "path": "/api/organizations/{id}/data", "permission": "privacy:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "id", "confirmation" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/00000000-0000-4000-8000-000000000000/data", "body": null }, "effects": "May change state through DELETE /api/organizations/{id}/data. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "preferences.get", "title": "Get user preferences", "description": "Get Socialize user preferences.", "method": "GET", "path": "/api/user/preferences", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get user preferences.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/user/preferences", "body": null }, "effects": "Reads state through GET /api/user/preferences without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/user/preferences", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "preferences.update", "title": "Update user preferences", "description": "Update Socialize user preferences.", "method": "PUT", "path": "/api/user/preferences", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "theme": { "type": "string" }, "language": { "type": "string" }, "timezone": { "type": "string" }, "notifications": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "dashboard": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "calendar": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "analytics": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update user preferences.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "theme": "example", "language": "example", "timezone": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/user/preferences", "body": { "theme": "example", "language": "example", "timezone": "example" } }, "effects": "May change state through PUT /api/user/preferences. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/user/preferences", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "integrations.list", "title": "List integrations", "description": "List Socialize integrations.", "method": "GET", "path": "/api/integrations", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List integrations.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/integrations", "body": null }, "effects": "Reads state through GET /api/integrations without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/integrations", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "integrations.connect", "title": "Connect integration", "description": "Start a Socialize integration connection.", "method": "POST", "path": "/api/integrations/{platform}/connect", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "platform": { "type": "string", "minLength": 1 }, "callbackUrl": { "type": "string", "format": "uri" } }, "required": [ "platform" ], "additionalProperties": false }, "target": "api", "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "authUrl": { "type": "string", "format": "uri" }, "state": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "authUrl", "state", "expiresAt" ], "additionalProperties": false }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/applications/socialize#integrations", "resource": { "kind": "brand", "idPath": "brandId" }, "effects": [ "Creates a short-lived OAuth state and returns the provider authorization URL; it does not complete the connection." ], "errors": [ { "status": 400, "code": "unsupported_platform", "recovery": "Call integrations.list and choose a connectable provider id." }, { "status": 409, "code": "integration_misconfigured", "recovery": "Configure the provider OAuth credential in Nexus for Socialize and this environment." }, { "status": 503, "code": "integration_dependency_unavailable", "recovery": "Retry the action. If it continues, inspect Auth service-token exchange and Nexus availability using the request ID." } ], "verify": [ "Open authUrl for the user, complete provider consent, then call integrations.list and confirm an active connection for the selected provider." ], "nextActionIds": [ "app_topolo_socialize.integrations.list" ], "examples": [ { "title": "Begin a personal LinkedIn connection", "description": "Returns the LinkedIn consent URL for the active Socialize brand.", "input": { "platform": "linkedin" } } ] }, "documentation": { "example_input": { "platform": "linkedin" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/integrations/linkedin/connect", "body": { "platform": "linkedin" } }, "effects": "Creates a short-lived OAuth state and returns the provider authorization URL; it does not complete the connection.", "verification": [ "Open authUrl for the user, complete provider consent, then call integrations.list and confirm an active connection for the selected provider." ], "recovery": [ "400 unsupported_platform: Call integrations.list and choose a connectable provider id.", "409 integration_misconfigured: Configure the provider OAuth credential in Nexus for Socialize and this environment.", "503 integration_dependency_unavailable: Retry the action. If it continues, inspect Auth service-token exchange and Nexus availability using the request ID." ], "docs_url": "https://docs.topolo.app/applications/socialize#integrations", "resource": { "kind": "brand", "idPath": "brandId" }, "next_action_ids": [ "app_topolo_socialize.integrations.list" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/integrations/*/connect", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "integrations.linkedin_organization.update", "title": "Update LinkedIn organization", "description": "Update Socialize LinkedIn organization.", "method": "PUT", "path": "/api/integrations/linkedin/organization", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "organizationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update LinkedIn organization.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "organizationId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/integrations/linkedin/organization", "body": { "organizationId": "example" } }, "effects": "May change state through PUT /api/integrations/linkedin/organization. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/integrations/linkedin/organization", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "integrations.facebook_page.update", "title": "Update Facebook page", "description": "Update Socialize Facebook page.", "method": "PUT", "path": "/api/integrations/facebook/page", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pageId": { "type": "string", "minLength": 1 } }, "required": [ "pageId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update Facebook page.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "pageId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/integrations/facebook/page", "body": { "pageId": "example" } }, "effects": "May change state through PUT /api/integrations/facebook/page. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/integrations/facebook/page", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "integrations.nickname.update", "title": "Update integration nickname", "description": "Update a Socialize integration nickname.", "method": "PUT", "path": "/api/integrations/{id}/nickname", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "nickname": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "nickname" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update integration nickname.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "nickname": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/integrations/00000000-0000-4000-8000-000000000000/nickname", "body": { "id": "00000000-0000-4000-8000-000000000000", "nickname": "example" } }, "effects": "May change state through PUT /api/integrations/{id}/nickname. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/integrations/*/nickname", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "integrations.disconnect", "title": "Disconnect integration", "description": "Disconnect a Socialize integration.", "method": "DELETE", "path": "/api/integrations/{id}", "permission": "accounts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Disconnect integration.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/integrations/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/integrations/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/integrations/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.generate_image", "title": "Generate image", "description": "Generate a Socialize image.", "method": "POST", "path": "/api/ai/generate-image", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "prompt": { "type": "string", "minLength": 10, "maxLength": 1000 }, "negativePrompt": { "type": "string", "maxLength": 500 }, "aspectRatio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4" ] }, "numberOfImages": { "type": "number", "minimum": 1, "maximum": 4 }, "style": { "type": "string", "enum": [ "photorealistic", "digital_art", "watercolor", "oil_painting", "sketch" ] }, "preprocessPrompt": { "type": "boolean" }, "postContent": { "type": "string", "maxLength": 2000 }, "provider": { "type": "string", "enum": [ "openai", "google", "xai", "cloudflare" ] }, "model": { "type": "string", "maxLength": 200 } }, "required": [ "prompt" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Generate image.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "prompt": "examplexxx" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/generate-image", "body": { "prompt": "examplexxx" } }, "effects": "May change state through POST /api/ai/generate-image. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/generate-image", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.generate_programmatic_image", "title": "Generate programmatic image", "description": "Generate a Socialize programmatic image.", "method": "POST", "path": "/api/ai/generate-programmatic-image", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 2000 }, "template": { "type": "string", "enum": [ "quote", "stat", "comparison", "announcement", "list", "pricing", "thread_hook", "milestone" ] }, "aspectRatio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "4:5" ] }, "channel": { "type": "string", "enum": [ "twitter", "x", "linkedin", "linkedin_company", "facebook", "instagram", "threads", "tiktok", "youtube" ] }, "claimIds": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1 } }, "ctaId": { "type": "string", "minLength": 1 } }, "required": [ "content" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Generate programmatic image.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "content": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/generate-programmatic-image", "body": { "content": "example" } }, "effects": "May change state through POST /api/ai/generate-programmatic-image. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/generate-programmatic-image", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.programmatic_config.get", "title": "Get programmatic config", "description": "Get Socialize programmatic image config.", "method": "GET", "path": "/api/ai/programmatic-config", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get programmatic config.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/programmatic-config", "body": null }, "effects": "Reads state through GET /api/ai/programmatic-config without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/programmatic-config", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.update_image", "title": "Update image", "description": "Update a Socialize item image.", "method": "POST", "path": "/api/ai/update-image", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "itemType": { "type": "string", "enum": [ "suggestion", "post" ] }, "itemId": { "type": "string", "minLength": 1 }, "imageUrl": { "type": "string", "minLength": 1 } }, "required": [ "itemType", "itemId", "imageUrl" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update image.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "itemType": "suggestion", "itemId": "example", "imageUrl": "https://example.com" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/update-image", "body": { "itemType": "suggestion", "itemId": "example", "imageUrl": "https://example.com" } }, "effects": "May change state through POST /api/ai/update-image. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/update-image", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.config.get", "title": "Get AI config", "description": "Get Socialize AI config.", "method": "GET", "path": "/api/ai/config", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get AI config.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/config", "body": null }, "effects": "Reads state through GET /api/ai/config without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/config", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.images.list", "title": "List AI images", "description": "List Socialize AI images.", "method": "GET", "path": "/api/ai/images", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentTypeId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "favoritesOnly": { "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List AI images.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "contentTypeId": "example", "limit": 1, "offset": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/images", "body": null }, "effects": "Reads state through GET /api/ai/images without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/images", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.library.list", "title": "List AI library", "description": "List Socialize AI library items.", "method": "GET", "path": "/api/ai/library", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentTypeId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "favoritesOnly": { "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List AI library.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "contentTypeId": "example", "limit": 1, "offset": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/library", "body": null }, "effects": "Reads state through GET /api/ai/library without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/library", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.library.create", "title": "Create AI library item", "description": "Create a Socialize AI library item.", "method": "POST", "path": "/api/ai/library", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentTypeId": { "type": "string", "minLength": 1 }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "output": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "tone": { "type": "string", "minLength": 1 }, "length": { "type": "string", "minLength": 1 }, "brandVoiceSnapshot": {}, "authenticityControlsSnapshot": {}, "aiLikenessScore": {}, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "isFavorite": { "type": "boolean" }, "mediaUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "contentTypeId", "inputs", "output", "tone", "length" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create AI library item.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "contentTypeId": "example", "inputs": {}, "output": {}, "tone": "example", "length": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/library", "body": { "contentTypeId": "example", "inputs": {}, "output": {}, "tone": "example", "length": "example" } }, "effects": "May change state through POST /api/ai/library. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/library", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.library.delete", "title": "Delete AI library item", "description": "Delete a Socialize AI library item.", "method": "DELETE", "path": "/api/ai/library/{id}", "permission": "posts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete AI library item.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/ai/library/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/ai/library/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/ai/library/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.library.favorite", "title": "Favorite AI library item", "description": "Toggle favorite on a Socialize AI library item.", "method": "PATCH", "path": "/api/ai/library/{id}/favorite", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Favorite AI library item.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/ai/library/00000000-0000-4000-8000-000000000000/favorite", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PATCH /api/ai/library/{id}/favorite. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/ai/library/*/favorite", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.trends.list", "title": "List AI trends", "description": "List Socialize AI trends.", "method": "GET", "path": "/api/ai/trends", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "platforms": { "type": "string" }, "region": { "type": "string", "enum": [ "global", "us", "uk", "eu", "uae", "india", "asia-pacific", "latam" ] }, "language": { "type": "string", "maxLength": 10 }, "topics": { "type": "string" }, "timeWindow": { "type": "string", "enum": [ "24h", "7d" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "forceRefresh": { "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List AI trends.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "platforms": "example", "region": "global", "language": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/trends", "body": null }, "effects": "Reads state through GET /api/ai/trends without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/trends", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.trends.saved.list", "title": "List saved AI trends", "description": "List saved Socialize AI trends.", "method": "GET", "path": "/api/ai/trends/saved", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List saved AI trends.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/trends/saved", "body": null }, "effects": "Reads state through GET /api/ai/trends/saved without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/trends/saved", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.trends.save", "title": "Save AI trend", "description": "Save a Socialize AI trend.", "method": "POST", "path": "/api/ai/trends/save", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "trendId": { "type": "string", "minLength": 1 }, "notes": { "type": "string", "maxLength": 500 } }, "required": [ "trendId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Save AI trend.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "trendId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/trends/save", "body": { "trendId": "example" } }, "effects": "May change state through POST /api/ai/trends/save. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/trends/save", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.trends.health.get", "title": "Get trend provider health", "description": "Get Socialize trend provider health.", "method": "GET", "path": "/api/ai/trends/health", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get trend provider health.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/trends/health", "body": null }, "effects": "Reads state through GET /api/ai/trends/health without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/trends/health", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.x_research.get", "title": "Get X research", "description": "Get Socialize X research.", "method": "GET", "path": "/api/ai/x-research", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "handle": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 20 }, "days": { "type": "integer", "minimum": 1, "maximum": 30 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get X research.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "handle": "example", "limit": 1, "days": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/x-research", "body": null }, "effects": "Reads state through GET /api/ai/x-research without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/x-research", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "trends.list", "title": "List trends", "description": "List Socialize content strategy trends.", "method": "GET", "path": "/api/trends", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List trends.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "source": "example", "limit": 1, "offset": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/trends", "body": null }, "effects": "Reads state through GET /api/trends without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/trends", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.trends.get", "title": "Get AI trend", "description": "Get a Socialize AI trend.", "method": "GET", "path": "/api/ai/trends/{id}", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get AI trend.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/trends/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/ai/trends/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/trends/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.trends.generate", "title": "Generate from AI trend", "description": "Generate Socialize content from an AI trend.", "method": "POST", "path": "/api/ai/trends/{id}/generate", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "enum": [ "linkedin", "x", "instagram", "tiktok", "youtube" ] }, "selectedAngleIndex": { "type": "number" }, "selectedHookIndex": { "type": "number" }, "tone": { "type": "string" }, "length": { "type": "string" }, "brandVoice": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "platform" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Generate from AI trend.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "platform": "linkedin" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/trends/00000000-0000-4000-8000-000000000000/generate", "body": { "id": "00000000-0000-4000-8000-000000000000", "platform": "linkedin" } }, "effects": "May change state through POST /api/ai/trends/{id}/generate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/trends/*/generate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.trends.saved.delete", "title": "Delete saved AI trend", "description": "Delete a saved Socialize AI trend.", "method": "DELETE", "path": "/api/ai/trends/saved/{id}", "permission": "posts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete saved AI trend.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/ai/trends/saved/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/ai/trends/saved/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/ai/trends/saved/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_voice.presets.list", "title": "List brand voice presets", "description": "List Socialize brand voice presets.", "method": "GET", "path": "/api/brand-voice/presets", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List brand voice presets.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "limit": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand-voice/presets", "body": null }, "effects": "Reads state through GET /api/brand-voice/presets without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand-voice/presets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "integrations.linkedin_company_organization.update", "title": "Integrations Linkedin Company Organization Update", "description": "Call PUT /api/integrations/linkedin_company/organization.", "method": "PUT", "path": "/api/integrations/linkedin_company/organization", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "organizationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Integrations Linkedin Company Organization Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "organizationId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/integrations/linkedin_company/organization", "body": { "organizationId": "example" } }, "effects": "May change state through PUT /api/integrations/linkedin_company/organization. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/integrations/linkedin_company/organization", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_voice.presets.builtin.list", "title": "Brand Voice Presets Builtin List", "description": "Call GET /api/brand-voice/presets/builtin.", "method": "GET", "path": "/api/brand-voice/presets/builtin", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand Voice Presets Builtin List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand-voice/presets/builtin", "body": null }, "effects": "Reads state through GET /api/brand-voice/presets/builtin without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand-voice/presets/builtin", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_voice.presets.default.get", "title": "Brand Voice Presets Default Get", "description": "Call GET /api/brand-voice/presets/default.", "method": "GET", "path": "/api/brand-voice/presets/default", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand Voice Presets Default Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand-voice/presets/default", "body": null }, "effects": "Reads state through GET /api/brand-voice/presets/default without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand-voice/presets/default", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_voice.presets.create", "title": "Brand Voice Presets Create", "description": "Call POST /api/brand-voice/presets.", "method": "POST", "path": "/api/brand-voice/presets", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "tone": { "type": "string" }, "audience": { "type": "string" }, "styleRules": { "type": "array", "items": { "type": "string" } }, "examples": { "type": "array", "items": { "type": "string" } }, "isDefault": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand Voice Presets Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "name": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brand-voice/presets", "body": { "name": "example" } }, "effects": "May change state through POST /api/brand-voice/presets. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brand-voice/presets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_voice.presets.set_default", "title": "Brand Voice Presets Set Default", "description": "Call POST /api/brand-voice/presets/{id}/default.", "method": "POST", "path": "/api/brand-voice/presets/{id}/default", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand Voice Presets Set Default.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brand-voice/presets/00000000-0000-4000-8000-000000000000/default", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/brand-voice/presets/{id}/default. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brand-voice/presets/*/default", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_voice.presets.duplicate", "title": "Brand Voice Presets Duplicate", "description": "Call POST /api/brand-voice/presets/{id}/duplicate.", "method": "POST", "path": "/api/brand-voice/presets/{id}/duplicate", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand Voice Presets Duplicate.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brand-voice/presets/00000000-0000-4000-8000-000000000000/duplicate", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/brand-voice/presets/{id}/duplicate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brand-voice/presets/*/duplicate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_voice.presets.get", "title": "Brand Voice Presets Get", "description": "Call GET /api/brand-voice/presets/{id}.", "method": "GET", "path": "/api/brand-voice/presets/{id}", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand Voice Presets Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand-voice/presets/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/brand-voice/presets/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand-voice/presets/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_voice.presets.update", "title": "Brand Voice Presets Update", "description": "Call PUT /api/brand-voice/presets/{id}.", "method": "PUT", "path": "/api/brand-voice/presets/{id}", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "tone": { "type": "string" }, "audience": { "type": "string" }, "styleRules": { "type": "array", "items": { "type": "string" } }, "examples": { "type": "array", "items": { "type": "string" } }, "isDefault": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand Voice Presets Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/brand-voice/presets/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/brand-voice/presets/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/brand-voice/presets/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_voice.presets.delete", "title": "Brand Voice Presets Delete", "description": "Call DELETE /api/brand-voice/presets/{id}.", "method": "DELETE", "path": "/api/brand-voice/presets/{id}", "permission": "posts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand Voice Presets Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/brand-voice/presets/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/brand-voice/presets/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/brand-voice/presets/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_voice.audit.list", "title": "Brand Voice Audit List", "description": "Call GET /api/brand-voice/audit.", "method": "GET", "path": "/api/brand-voice/audit", "permission": "analytics:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand Voice Audit List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "limit": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand-voice/audit", "body": null }, "effects": "Reads state through GET /api/brand-voice/audit without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand-voice/audit", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand.ctas.list", "title": "Brand Ctas List", "description": "Call GET /api/brand/ctas.", "method": "GET", "path": "/api/brand/ctas", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand Ctas List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand/ctas", "body": null }, "effects": "Reads state through GET /api/brand/ctas without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand/ctas", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand.ctas.create", "title": "Brand Ctas Create", "description": "Call POST /api/brand/ctas.", "method": "POST", "path": "/api/brand/ctas", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "url": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "category": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "priority": { "type": "number" } }, "required": [ "label", "url" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand Ctas Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "label": "example", "url": "https://example.com" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brand/ctas", "body": { "label": "example", "url": "https://example.com" } }, "effects": "May change state through POST /api/brand/ctas. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brand/ctas", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand.ctas.update", "title": "Brand Ctas Update", "description": "Call PUT /api/brand/ctas/{id}.", "method": "PUT", "path": "/api/brand/ctas/{id}", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "url": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "category": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "priority": { "type": "number" }, "isActive": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand Ctas Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/brand/ctas/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/brand/ctas/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/brand/ctas/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand.ctas.delete", "title": "Brand Ctas Delete", "description": "Call DELETE /api/brand/ctas/{id}.", "method": "DELETE", "path": "/api/brand/ctas/{id}", "permission": "accounts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand Ctas Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/brand/ctas/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/brand/ctas/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/brand/ctas/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand.x_mentions.list", "title": "Brand X Mentions List", "description": "Call GET /api/brand/x-mentions.", "method": "GET", "path": "/api/brand/x-mentions", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand X Mentions List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand/x-mentions", "body": null }, "effects": "Reads state through GET /api/brand/x-mentions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand/x-mentions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand.x_mentions.create", "title": "Brand X Mentions Create", "description": "Call POST /api/brand/x-mentions.", "method": "POST", "path": "/api/brand/x-mentions", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entityName": { "type": "string", "minLength": 1 }, "xHandle": { "type": "string", "minLength": 1 }, "entityType": { "type": "string" }, "relationship": { "type": "string" }, "notes": { "type": "string" }, "autoTag": { "type": "boolean" } }, "required": [ "entityName", "xHandle" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand X Mentions Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "entityName": "example", "xHandle": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brand/x-mentions", "body": { "entityName": "example", "xHandle": "example" } }, "effects": "May change state through POST /api/brand/x-mentions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brand/x-mentions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand.x_mentions.update", "title": "Brand X Mentions Update", "description": "Call PUT /api/brand/x-mentions/{id}.", "method": "PUT", "path": "/api/brand/x-mentions/{id}", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "entityName": { "type": "string", "minLength": 1 }, "xHandle": { "type": "string", "minLength": 1 }, "entityType": { "type": "string" }, "relationship": { "type": "string" }, "notes": { "type": "string" }, "autoTag": { "type": "boolean" }, "isVerified": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand X Mentions Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/brand/x-mentions/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/brand/x-mentions/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/brand/x-mentions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand.x_mentions.delete", "title": "Brand X Mentions Delete", "description": "Call DELETE /api/brand/x-mentions/{id}.", "method": "DELETE", "path": "/api/brand/x-mentions/{id}", "permission": "accounts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brand X Mentions Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/brand/x-mentions/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/brand/x-mentions/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/brand/x-mentions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.engagement_targets.list", "title": "Content Strategy Engagement Targets List", "description": "Call GET /api/content-strategy/engagement-targets.", "method": "GET", "path": "/api/content-strategy/engagement-targets", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "activeOnly": { "type": "string", "enum": [ "true", "false" ] }, "brandId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Engagement Targets List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "activeOnly": "true", "brandId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/content-strategy/engagement-targets", "body": null }, "effects": "Reads state through GET /api/content-strategy/engagement-targets without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/content-strategy/engagement-targets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.engagement_targets.create", "title": "Content Strategy Engagement Targets Create", "description": "Call POST /api/content-strategy/engagement-targets.", "method": "POST", "path": "/api/content-strategy/engagement-targets", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "platform": { "type": "string" }, "username": { "type": "string", "minLength": 1 }, "displayName": { "type": "string" }, "notes": { "type": "string" }, "priority": { "type": "number" }, "active": { "type": "boolean" } }, "required": [ "platform", "username" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Engagement Targets Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "platform": "example", "username": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/content-strategy/engagement-targets", "body": { "platform": "example", "username": "example" } }, "effects": "May change state through POST /api/content-strategy/engagement-targets. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/content-strategy/engagement-targets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.engagement_targets.get", "title": "Content Strategy Engagement Targets Get", "description": "Call GET /api/content-strategy/engagement-targets/{id}.", "method": "GET", "path": "/api/content-strategy/engagement-targets/{id}", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Engagement Targets Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/content-strategy/engagement-targets/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/content-strategy/engagement-targets/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/content-strategy/engagement-targets/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.engagement_targets.update", "title": "Content Strategy Engagement Targets Update", "description": "Call PUT /api/content-strategy/engagement-targets/{id}.", "method": "PUT", "path": "/api/content-strategy/engagement-targets/{id}", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "platform": { "type": "string" }, "username": { "type": "string", "minLength": 1 }, "displayName": { "type": "string" }, "notes": { "type": "string" }, "priority": { "type": "number" }, "active": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Engagement Targets Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/content-strategy/engagement-targets/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/content-strategy/engagement-targets/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/content-strategy/engagement-targets/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.engagement_targets.delete", "title": "Content Strategy Engagement Targets Delete", "description": "Call DELETE /api/content-strategy/engagement-targets/{id}.", "method": "DELETE", "path": "/api/content-strategy/engagement-targets/{id}", "permission": "posts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Engagement Targets Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/content-strategy/engagement-targets/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/content-strategy/engagement-targets/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/content-strategy/engagement-targets/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.topics.list", "title": "Content Strategy Topics List", "description": "Call GET /api/content-strategy/topics.", "method": "GET", "path": "/api/content-strategy/topics", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "activeOnly": { "type": "string", "enum": [ "true", "false" ] }, "brandId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Topics List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "activeOnly": "true", "brandId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/content-strategy/topics", "body": null }, "effects": "Reads state through GET /api/content-strategy/topics without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/content-strategy/topics", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.topics.create", "title": "Content Strategy Topics Create", "description": "Call POST /api/content-strategy/topics.", "method": "POST", "path": "/api/content-strategy/topics", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "topic": { "type": "string", "minLength": 1 }, "weight": { "type": "number" }, "active": { "type": "boolean" } }, "required": [ "topic" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Topics Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "topic": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/content-strategy/topics", "body": { "topic": "example" } }, "effects": "May change state through POST /api/content-strategy/topics. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/content-strategy/topics", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.topics.update", "title": "Content Strategy Topics Update", "description": "Call PUT /api/content-strategy/topics/{id}.", "method": "PUT", "path": "/api/content-strategy/topics/{id}", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "topic": { "type": "string", "minLength": 1 }, "weight": { "type": "number" }, "active": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Topics Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/content-strategy/topics/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/content-strategy/topics/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/content-strategy/topics/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.topics.delete", "title": "Content Strategy Topics Delete", "description": "Call DELETE /api/content-strategy/topics/{id}.", "method": "DELETE", "path": "/api/content-strategy/topics/{id}", "permission": "posts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Topics Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/content-strategy/topics/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/content-strategy/topics/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/content-strategy/topics/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.pillars.list", "title": "Content Strategy Pillars List", "description": "Call GET /api/content-strategy/pillars.", "method": "GET", "path": "/api/content-strategy/pillars", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "activeOnly": { "type": "string", "enum": [ "true", "false" ] }, "brandId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Pillars List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "activeOnly": "true", "brandId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/content-strategy/pillars", "body": null }, "effects": "Reads state through GET /api/content-strategy/pillars without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/content-strategy/pillars", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.pillars.create", "title": "Content Strategy Pillars Create", "description": "Call POST /api/content-strategy/pillars.", "method": "POST", "path": "/api/content-strategy/pillars", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "weight": { "type": "number" }, "active": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Pillars Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "name": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/content-strategy/pillars", "body": { "name": "example" } }, "effects": "May change state through POST /api/content-strategy/pillars. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/content-strategy/pillars", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.pillars.update", "title": "Content Strategy Pillars Update", "description": "Call PUT /api/content-strategy/pillars/{id}.", "method": "PUT", "path": "/api/content-strategy/pillars/{id}", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "weight": { "type": "number" }, "active": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Pillars Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/content-strategy/pillars/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/content-strategy/pillars/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/content-strategy/pillars/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.pillars.delete", "title": "Content Strategy Pillars Delete", "description": "Call DELETE /api/content-strategy/pillars/{id}.", "method": "DELETE", "path": "/api/content-strategy/pillars/{id}", "permission": "posts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Pillars Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/content-strategy/pillars/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/content-strategy/pillars/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/content-strategy/pillars/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.platform_preferences.list", "title": "Content Strategy Platform Preferences List", "description": "Call GET /api/content-strategy/platform-preferences.", "method": "GET", "path": "/api/content-strategy/platform-preferences", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Platform Preferences List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/content-strategy/platform-preferences", "body": null }, "effects": "Reads state through GET /api/content-strategy/platform-preferences without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/content-strategy/platform-preferences", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.platform_preferences.create", "title": "Content Strategy Platform Preferences Create", "description": "Call POST /api/content-strategy/platform-preferences.", "method": "POST", "path": "/api/content-strategy/platform-preferences", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "platform": { "type": "string" }, "enabled": { "type": "boolean" }, "postingFrequency": { "type": "string" }, "tone": { "type": "string" }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "platform" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Platform Preferences Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "platform": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/content-strategy/platform-preferences", "body": { "platform": "example" } }, "effects": "May change state through POST /api/content-strategy/platform-preferences. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/content-strategy/platform-preferences", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.generate", "title": "Content Strategy Generate", "description": "Call POST /api/content-strategy/generate.", "method": "POST", "path": "/api/content-strategy/generate", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "goals": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "string" } }, "prompt": { "type": "string" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Generate.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "brandId": "example", "goals": [ "example" ], "platforms": [ "example" ] }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/content-strategy/generate", "body": { "brandId": "example", "goals": [ "example" ], "platforms": [ "example" ] } }, "effects": "May change state through POST /api/content-strategy/generate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/content-strategy/generate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.suggestions.list", "title": "Content Strategy Suggestions List", "description": "Call GET /api/content-strategy/suggestions.", "method": "GET", "path": "/api/content-strategy/suggestions", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "brandId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Suggestions List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "status": "example", "platform": "example", "limit": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/content-strategy/suggestions", "body": null }, "effects": "Reads state through GET /api/content-strategy/suggestions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/content-strategy/suggestions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.suggestions.generate", "title": "Content Strategy Suggestions Generate", "description": "Call POST /api/content-strategy/suggestions/generate.", "method": "POST", "path": "/api/content-strategy/suggestions/generate", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "platform": { "type": "string", "minLength": 1 }, "topic": { "type": "string" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Suggestions Generate.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "count": 1, "platform": "example", "topic": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/content-strategy/suggestions/generate", "body": { "count": 1, "platform": "example", "topic": "example" } }, "effects": "May change state through POST /api/content-strategy/suggestions/generate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/content-strategy/suggestions/generate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.suggestions.generate_batch", "title": "Content Strategy Suggestions Generate Batch", "description": "Call POST /api/content-strategy/suggestions/generate-batch.", "method": "POST", "path": "/api/content-strategy/suggestions/generate-batch", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "platforms": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Suggestions Generate Batch.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "count": 1, "platforms": [ "example" ], "topics": [ "example" ] }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/content-strategy/suggestions/generate-batch", "body": { "count": 1, "platforms": [ "example" ], "topics": [ "example" ] } }, "effects": "May change state through POST /api/content-strategy/suggestions/generate-batch. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/content-strategy/suggestions/generate-batch", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.suggestions.generate_from_trends", "title": "Content Strategy Suggestions Generate From Trends", "description": "Call POST /api/content-strategy/suggestions/generate-from-trends.", "method": "POST", "path": "/api/content-strategy/suggestions/generate-from-trends", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "trendIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Suggestions Generate From Trends.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "trendIds": [ "example" ], "limit": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/content-strategy/suggestions/generate-from-trends", "body": { "trendIds": [ "example" ], "limit": 1 } }, "effects": "May change state through POST /api/content-strategy/suggestions/generate-from-trends. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/content-strategy/suggestions/generate-from-trends", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.engagement_feed.list", "title": "Content Strategy Engagement Feed List", "description": "Call GET /api/content-strategy/engagement-feed.", "method": "GET", "path": "/api/content-strategy/engagement-feed", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "suggestions": { "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Engagement Feed List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "limit": 1, "suggestions": "true" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/content-strategy/engagement-feed", "body": null }, "effects": "Reads state through GET /api/content-strategy/engagement-feed without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/content-strategy/engagement-feed", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.suggestions.get", "title": "Content Strategy Suggestions Get", "description": "Call GET /api/content-strategy/suggestions/{id}.", "method": "GET", "path": "/api/content-strategy/suggestions/{id}", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Suggestions Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/content-strategy/suggestions/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/content-strategy/suggestions/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/content-strategy/suggestions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.suggestions.update", "title": "Content Strategy Suggestions Update", "description": "Call PUT /api/content-strategy/suggestions/{id}.", "method": "PUT", "path": "/api/content-strategy/suggestions/{id}", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "imageUrl": { "type": "string" }, "deferredUntil": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Suggestions Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/content-strategy/suggestions/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/content-strategy/suggestions/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/content-strategy/suggestions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.suggestions.delete", "title": "Content Strategy Suggestions Delete", "description": "Call DELETE /api/content-strategy/suggestions/{id}.", "method": "DELETE", "path": "/api/content-strategy/suggestions/{id}", "permission": "posts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Suggestions Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/content-strategy/suggestions/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/content-strategy/suggestions/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/content-strategy/suggestions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.feedback.list", "title": "Content Strategy Feedback List", "description": "Call GET /api/content-strategy/feedback.", "method": "GET", "path": "/api/content-strategy/feedback", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Feedback List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "type": "example", "limit": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/content-strategy/feedback", "body": null }, "effects": "Reads state through GET /api/content-strategy/feedback without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/content-strategy/feedback", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.feedback.create", "title": "Content Strategy Feedback Create", "description": "Call POST /api/content-strategy/feedback.", "method": "POST", "path": "/api/content-strategy/feedback", "permission": "posts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "type", "message" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Feedback Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "type": "example", "message": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/content-strategy/feedback", "body": { "type": "example", "message": "example" } }, "effects": "May change state through POST /api/content-strategy/feedback. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/content-strategy/feedback", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "content_strategy.feedback.delete", "title": "Content Strategy Feedback Delete", "description": "Call DELETE /api/content-strategy/feedback/{id}.", "method": "DELETE", "path": "/api/content-strategy/feedback/{id}", "permission": "posts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Content Strategy Feedback Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/content-strategy/feedback/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/content-strategy/feedback/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/content-strategy/feedback/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.publishing_readiness.get", "title": "Brands Publishing Readiness Get", "description": "Call GET /api/brands/{id}/publishing-readiness.", "method": "GET", "path": "/api/brands/{id}/publishing-readiness", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "platforms": { "type": "object", "properties": { "x": { "type": "object", "properties": { "connected": { "type": "boolean" }, "canSchedule": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "account_not_connected", "connection_error", "token_expired", "connection_unavailable" ] } }, "required": [ "connected", "canSchedule" ], "additionalProperties": false }, "linkedin": { "type": "object", "properties": { "connected": { "type": "boolean" }, "canSchedule": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "account_not_connected", "connection_error", "token_expired", "connection_unavailable" ] } }, "required": [ "connected", "canSchedule" ], "additionalProperties": false }, "facebook": { "type": "object", "properties": { "connected": { "type": "boolean" }, "canSchedule": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "account_not_connected", "connection_error", "token_expired", "connection_unavailable" ] } }, "required": [ "connected", "canSchedule" ], "additionalProperties": false }, "instagram": { "type": "object", "properties": { "connected": { "type": "boolean" }, "canSchedule": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "account_not_connected", "connection_error", "token_expired", "connection_unavailable" ] } }, "required": [ "connected", "canSchedule" ], "additionalProperties": false }, "threads": { "type": "object", "properties": { "connected": { "type": "boolean" }, "canSchedule": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "account_not_connected", "connection_error", "token_expired", "connection_unavailable" ] } }, "required": [ "connected", "canSchedule" ], "additionalProperties": false }, "tiktok": { "type": "object", "properties": { "connected": { "type": "boolean" }, "canSchedule": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "account_not_connected", "connection_error", "token_expired", "connection_unavailable" ] } }, "required": [ "connected", "canSchedule" ], "additionalProperties": false }, "youtube": { "type": "object", "properties": { "connected": { "type": "boolean" }, "canSchedule": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "account_not_connected", "connection_error", "token_expired", "connection_unavailable" ] } }, "required": [ "connected", "canSchedule" ], "additionalProperties": false } }, "required": [ "x", "linkedin", "facebook", "instagram", "threads", "tiktok", "youtube" ], "additionalProperties": false } }, "required": [ "brandId", "platforms" ], "additionalProperties": false }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/applications/socialize#publishing-readiness", "resource": { "kind": "brand", "idPath": "brandId" }, "effects": [ "Reads provider connection and token readiness without changing state." ], "errors": [ { "status": 404, "code": "brand_not_found", "recovery": "Resolve a brand id through brands.list in the same organization before checking publishing readiness." } ], "verify": [ "Require canSchedule=true for every target platform before scheduling or publishing." ], "nextActionIds": [ "app_topolo_socialize.posts.create", "app_topolo_socialize.campaigns.create" ] }, "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brands/00000000-0000-4000-8000-000000000000/publishing-readiness", "body": null }, "effects": "Reads provider connection and token readiness without changing state.", "verification": [ "Require canSchedule=true for every target platform before scheduling or publishing." ], "recovery": [ "404 brand_not_found: Resolve a brand id through brands.list in the same organization before checking publishing readiness." ], "docs_url": "https://docs.topolo.app/applications/socialize#publishing-readiness", "resource": { "kind": "brand", "idPath": "brandId" }, "next_action_ids": [ "app_topolo_socialize.posts.create", "app_topolo_socialize.campaigns.create" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brands/*/publishing-readiness", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.voice_context.list", "title": "Brands Voice Context List", "description": "Call GET /api/brands/{brandId}/voice-context.", "method": "GET", "path": "/api/brands/{brandId}/voice-context", "permission": "accounts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "document", "sample", "guideline", "faq", "competitor", "other" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "brandId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brands Voice Context List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "brandId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brands/example/voice-context", "body": null }, "effects": "Reads state through GET /api/brands/{brandId}/voice-context without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brands/*/voice-context", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.voice_context.create", "title": "Brands Voice Context Create", "description": "Call POST /api/brands/{brandId}/voice-context.", "method": "POST", "path": "/api/brands/{brandId}/voice-context", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "document", "sample", "guideline", "faq", "competitor", "other" ] }, "title": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "brandId", "title", "content" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brands Voice Context Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "brandId": "example", "title": "example", "content": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brands/example/voice-context", "body": { "brandId": "example", "title": "example", "content": "example" } }, "effects": "May change state through POST /api/brands/{brandId}/voice-context. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brands/*/voice-context", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.voice_context.bulk_create", "title": "Brands Voice Context Bulk Create", "description": "Call POST /api/brands/{brandId}/voice-context/bulk.", "method": "POST", "path": "/api/brands/{brandId}/voice-context/bulk", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "contexts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "sample", "guideline", "faq", "competitor", "other" ] }, "title": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "title", "content" ], "additionalProperties": false } } }, "required": [ "brandId", "contexts" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brands Voice Context Bulk Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "brandId": "example", "contexts": [ { "title": "example", "content": "example" } ] }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brands/example/voice-context/bulk", "body": { "brandId": "example", "contexts": [ { "title": "example", "content": "example" } ] } }, "effects": "May change state through POST /api/brands/{brandId}/voice-context/bulk. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brands/*/voice-context/bulk", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.voice_context.retrieve", "title": "Brands Voice Context Retrieve", "description": "Call POST /api/brands/{brandId}/voice-context/retrieve.", "method": "POST", "path": "/api/brands/{brandId}/voice-context/retrieve", "permission": "accounts:read", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "query": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 20 }, "type": { "type": "string", "enum": [ "document", "sample", "guideline", "faq", "competitor", "other" ] } }, "required": [ "brandId", "query" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brands Voice Context Retrieve.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "brandId": "example", "query": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brands/example/voice-context/retrieve", "body": { "brandId": "example", "query": "example" } }, "effects": "May change state through POST /api/brands/{brandId}/voice-context/retrieve. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brands/*/voice-context/retrieve", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.voice_context.stats.get", "title": "Brands Voice Context Stats Get", "description": "Call GET /api/brands/{brandId}/voice-context/stats.", "method": "GET", "path": "/api/brands/{brandId}/voice-context/stats", "permission": "analytics:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "document", "sample", "guideline", "faq", "competitor", "other" ] } }, "required": [ "brandId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brands Voice Context Stats Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "brandId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brands/example/voice-context/stats", "body": null }, "effects": "Reads state through GET /api/brands/{brandId}/voice-context/stats without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brands/*/voice-context/stats", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.voice_context.update", "title": "Brands Voice Context Update", "description": "Call PUT /api/brands/{brandId}/voice-context/{contextId}.", "method": "PUT", "path": "/api/brands/{brandId}/voice-context/{contextId}", "permission": "accounts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "contextId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "document", "sample", "guideline", "faq", "competitor", "other" ] }, "title": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "brandId", "contextId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brands Voice Context Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "brandId": "example", "contextId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/brands/example/voice-context/example", "body": { "brandId": "example", "contextId": "example" } }, "effects": "May change state through PUT /api/brands/{brandId}/voice-context/{contextId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/brands/*/voice-context/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.voice_context.delete", "title": "Brands Voice Context Delete", "description": "Call DELETE /api/brands/{brandId}/voice-context/{contextId}.", "method": "DELETE", "path": "/api/brands/{brandId}/voice-context/{contextId}", "permission": "accounts:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "contextId": { "type": "string", "minLength": 1 } }, "required": [ "brandId", "contextId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Brands Voice Context Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "brandId": "example", "contextId": "example" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/brands/example/voice-context/example", "body": null }, "effects": "May change state through DELETE /api/brands/{brandId}/voice-context/{contextId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/brands/*/voice-context/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.usage.get", "title": "Get AI usage", "description": "Get AI usage statistics for the selected brand.", "method": "GET", "path": "/api/ai/usage", "permission": "analytics:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/usage", "body": null }, "effects": "Reads state through GET /api/ai/usage without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/usage", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.usage.history", "title": "Get AI usage history", "description": "Get AI usage history for the selected brand.", "method": "GET", "path": "/api/ai/usage/history", "permission": "analytics:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 365 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "days": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/usage/history", "body": null }, "effects": "Reads state through GET /api/ai/usage/history without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/usage/history", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.usage.limits.get", "title": "Get AI usage limits", "description": "Get AI usage limits for the selected brand.", "method": "GET", "path": "/api/ai/usage/limits", "permission": "analytics:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/usage/limits", "body": null }, "effects": "Reads state through GET /api/ai/usage/limits without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/usage/limits", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.usage.limits.update", "title": "Update AI usage limits", "description": "Update AI usage limits for the selected brand.", "method": "PUT", "path": "/api/ai/usage/limits", "permission": "accounts:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "monthlyTokenLimit": { "type": "number", "minimum": 0 }, "dailyTokenLimit": { "type": "number", "minimum": 0 }, "monthlyCostLimitUsd": { "type": "number", "minimum": 0 }, "dailyCostLimitUsd": { "type": "number", "minimum": 0 }, "monthlyRequestLimit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dailyRequestLimit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "contentGenerationsPerDay": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "trendSearchesPerDay": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "imageGenerationsPerDay": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "suggestionsPerDay": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "notifyAtPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "notificationEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "hardLimit": { "type": "boolean" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "monthlyTokenLimit": 1, "dailyTokenLimit": 1, "monthlyCostLimitUsd": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/ai/usage/limits", "body": { "monthlyTokenLimit": 1, "dailyTokenLimit": 1, "monthlyCostLimitUsd": 1 } }, "effects": "May change state through PUT /api/ai/usage/limits. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/ai/usage/limits", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.usage.check", "title": "Check AI usage limits", "description": "Check whether an AI event is within the selected brand limits.", "method": "GET", "path": "/api/ai/usage/check", "permission": "analytics:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventType": { "type": "string", "enum": [ "content_generation", "trend_search", "image_generation", "suggestion", "brand_voice", "strategy_generation" ] } }, "required": [ "eventType" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "eventType": "content_generation" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/usage/check", "body": null }, "effects": "Reads state through GET /api/ai/usage/check without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/usage/check", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.usage.events.list", "title": "List AI usage events", "description": "List AI usage events for the selected brand.", "method": "GET", "path": "/api/ai/usage/events", "permission": "analytics:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "eventType": { "type": "string", "enum": [ "content_generation", "trend_search", "image_generation", "suggestion", "brand_voice", "strategy_generation" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "limit": 1, "offset": 1, "eventType": "content_generation" }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/usage/events", "body": null }, "effects": "Reads state through GET /api/ai/usage/events without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/usage/events", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "seeds.list", "title": "List shared seeds", "description": "List shared content-strategy seeds for the selected brand.", "method": "GET", "path": "/api/seeds", "permission": "posts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "limit": 1, "offset": 1 }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/seeds", "body": null }, "effects": "Reads state through GET /api/seeds without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/seeds", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "seeds.share", "title": "Share seed", "description": "Share a content-strategy seed and generate brand suggestions.", "method": "POST", "path": "/api/seeds/share", "permission": "posts:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source": { "type": "object", "properties": { "platform": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "sharedText": { "type": "string" }, "sharedAt": { "type": "string" } }, "required": [ "platform" ], "additionalProperties": false }, "targeting": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "one", "selected", "all" ] }, "brandIds": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "additionalProperties": false }, "priority": { "type": "string", "enum": [ "urgent", "normal" ] }, "userContext": { "type": "object", "properties": { "note": { "type": "string" } }, "additionalProperties": false } }, "required": [ "source" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "source": { "platform": "example" } }, "cli_example": [ "topolo actions --service socialize --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/seeds/share", "body": { "source": { "platform": "example" } } }, "effects": "May change state through POST /api/seeds/share. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/seeds/share", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 215, "matched_actions": 173, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 42, "configured_exclusions": 39, "configuration_findings": [], "notes": [ "analyzed source for api (manifest points at dist build)", "analyzed source for jobs (manifest points at dist build)", "3 manually-declared route(s)" ] }, "runtime_contract_audit": { "status": "verified", "actions": 173, "contracts": 173, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/index.ts" ], "authorization_sources": [ "apps/api/src/index.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloSocialize/topolo.mobile-experience.json", "contract": { "version": "2026-06-29", "status": "approved", "mode": "native_capability", "appId": "app_topolo_socialize", "localizationNamespace": "socialize", "permissions": [ "posts:read", "posts:write", "calendar:read", "calendar:write", "accounts:read", "accounts:write" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/posts", "auth": { "audience": "topolo-socialize", "scopes": [ "posts:read", "posts:write", "calendar:read", "calendar:write", "accounts:read", "accounts:write" ] }, "routes": [ { "path": "/posts", "apiPath": "/api/posts", "title": "Posts", "titleKey": "socialize.mobile.routes.posts.title", "template": "record.list", "dataSource": "socialize.posts.list", "detailRoute": "/posts/:id", "actions": [ { "id": "socialize.posts.create", "title": "Create post", "type": "record.create", "permission": "posts:write", "method": "POST", "path": "/api/posts", "fields": [ { "key": "content", "label": "Content", "type": "textarea", "required": true }, { "key": "platform", "label": "Platform", "type": "text", "required": true }, { "key": "scheduledFor", "label": "Scheduled for", "type": "datetime" }, { "key": "publishNow", "label": "Publish now", "type": "boolean" }, { "key": "status", "label": "Status", "type": "text" } ], "titleKey": "socialize.mobile.actions.posts.create.title" }, { "id": "socialize.posts.update", "title": "Update post", "type": "record.update", "permission": "posts:write", "method": "PUT", "path": "/api/posts/:id", "fields": [ { "key": "content", "label": "Content", "type": "textarea" }, { "key": "platform", "label": "Platform", "type": "text" }, { "key": "scheduledFor", "label": "Scheduled for", "type": "datetime" }, { "key": "publishNow", "label": "Publish now", "type": "boolean" }, { "key": "status", "label": "Status", "type": "text" } ], "titleKey": "socialize.mobile.actions.posts.update.title" }, { "id": "socialize.posts.delete", "title": "Delete post", "type": "record.delete", "permission": "posts:write", "method": "DELETE", "path": "/api/posts/:id", "titleKey": "socialize.mobile.actions.posts.delete.title" } ] }, { "path": "/posts/:id", "apiPath": "/api/posts/:id", "title": "Posts", "titleKey": "socialize.mobile.routes.posts.title", "template": "record.detail", "dataSource": "socialize.posts.detail" }, { "path": "/campaigns", "apiPath": "/api/campaigns", "title": "Campaigns", "titleKey": "socialize.mobile.routes.campaigns.title", "template": "record.list", "dataSource": "socialize.campaigns.list", "detailRoute": "/campaigns/:id", "actions": [ { "id": "socialize.campaigns.update", "title": "Update campaign", "type": "record.update", "permission": "calendar:write", "method": "PUT", "path": "/api/campaigns/:id", "fields": [ { "key": "name", "label": "Name", "type": "text" }, { "key": "description", "label": "Description", "type": "textarea" }, { "key": "status", "label": "Status", "type": "text" }, { "key": "windowStartDate", "label": "Window start", "type": "datetime" }, { "key": "windowEndDate", "label": "Window end", "type": "datetime" } ], "titleKey": "socialize.mobile.actions.campaigns.update.title" }, { "id": "socialize.campaigns.delete", "title": "Delete campaign", "type": "record.delete", "permission": "calendar:write", "method": "DELETE", "path": "/api/campaigns/:id", "titleKey": "socialize.mobile.actions.campaigns.delete.title" } ] }, { "path": "/campaigns/:id", "apiPath": "/api/campaigns/:id", "title": "Campaigns", "titleKey": "socialize.mobile.routes.campaigns.title", "template": "record.detail", "dataSource": "socialize.campaigns.detail" }, { "path": "/brands", "apiPath": "/api/brands", "title": "Brands", "titleKey": "socialize.mobile.routes.brands.title", "template": "record.list", "dataSource": "socialize.brands.list", "detailRoute": "/brands/:id", "actions": [ { "id": "socialize.brands.create", "title": "Create brand", "type": "record.create", "permission": "accounts:write", "method": "POST", "path": "/api/brands", "fields": [ { "key": "name", "label": "Name", "type": "text", "required": true }, { "key": "description", "label": "Description", "type": "textarea" } ], "titleKey": "socialize.mobile.actions.brands.create.title" }, { "id": "socialize.brands.update", "title": "Update brand", "type": "record.update", "permission": "accounts:write", "method": "PUT", "path": "/api/brands/:id", "fields": [ { "key": "name", "label": "Name", "type": "text" }, { "key": "description", "label": "Description", "type": "textarea" } ], "titleKey": "socialize.mobile.actions.brands.update.title" } ] }, { "path": "/brands/:id", "apiPath": "/api/brands/:id", "title": "Brands", "titleKey": "socialize.mobile.routes.brands.title", "template": "record.detail", "dataSource": "socialize.brands.detail" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "ALL", "path": "/healthz", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "ALL", "path": "/livez", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "ALL", "path": "/health", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "ALL", "path": "/status", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "ALL", "path": "/readyz", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "ALL", "path": "/api/internal/platform-connections/refresh-token", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "ALL", "path": "/api/internal/ai/generate-image", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "ALL", "path": "/version", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "ALL", "path": "/test-public-simple", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "ALL", "path": "/api/auth/*", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/public/join-request", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/public/grok-raw", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/public/trends-debug", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/public/trends-test", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/public/trend/:id", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/public/invite/:token", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/public/invite/:token/accept", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/integrations/:platform/callback", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/integrations/instagram/deauthorize", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/integrations/instagram/data-deletion", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/integrations/threads/deauthorize", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/integrations/threads/data-deletion", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "PUT", "path": "/api/media/upload/:id", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/widget", "source_path": "apps/TopoloSocialize/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/ai/generate-image", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/ai/generate-programmatic-image", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/ai/programmatic-config", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/ai/update-image", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/ai/config", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/ai/images", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/ai/generate-content", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/ai/library", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/ai/library", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "DELETE", "path": "/api/ai/library/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "PATCH", "path": "/api/ai/library/:id/favorite", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/ai/trends", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/ai/trends/saved", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/ai/trends/save", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/ai/trends/health", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/ai/x-research", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/trends", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/ai/trends/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/ai/trends/:id/generate", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "DELETE", "path": "/api/ai/trends/saved/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/scheduler/drafts/from-trend", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/brand-voice/presets", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/brand-voice/presets/builtin", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/brand-voice/presets/default", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/brand-voice/presets", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/brand-voice/presets/:id/default", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/brand-voice/presets/:id/duplicate", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/brand-voice/presets/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "PUT", "path": "/api/brand-voice/presets/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "DELETE", "path": "/api/brand-voice/presets/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/brand-voice/audit", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/brand/ctas", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/brand/ctas", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "PUT", "path": "/api/brand/ctas/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "DELETE", "path": "/api/brand/ctas/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/brand/x-mentions", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/brand/x-mentions", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "PUT", "path": "/api/brand/x-mentions/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "DELETE", "path": "/api/brand/x-mentions/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/content-strategy/engagement-targets", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/content-strategy/engagement-targets", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/content-strategy/engagement-targets/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "PUT", "path": "/api/content-strategy/engagement-targets/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "DELETE", "path": "/api/content-strategy/engagement-targets/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/content-strategy/topics", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/content-strategy/topics", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "PUT", "path": "/api/content-strategy/topics/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "DELETE", "path": "/api/content-strategy/topics/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/content-strategy/pillars", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/content-strategy/pillars", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "PUT", "path": "/api/content-strategy/pillars/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "DELETE", "path": "/api/content-strategy/pillars/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/content-strategy/platform-preferences", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/content-strategy/platform-preferences", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/ai/usage", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/ai/usage/history", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/ai/usage/limits", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "PUT", "path": "/api/ai/usage/limits", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/ai/usage/check", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/ai/usage/events", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/content-strategy/generate", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/content-strategy/suggestions", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/content-strategy/suggestions/generate", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/content-strategy/suggestions/generate-batch", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/content-strategy/suggestions/generate-from-trends", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/seeds", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/seeds/share", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/content-strategy/engagement-feed", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/content-strategy/suggestions/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "PUT", "path": "/api/content-strategy/suggestions/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "DELETE", "path": "/api/content-strategy/suggestions/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/content-strategy/feedback", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/content-strategy/feedback", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "DELETE", "path": "/api/content-strategy/feedback/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/brands/:id/publishing-readiness", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/brands/:brandId/voice-context", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/brands/:brandId/voice-context", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/brands/:brandId/voice-context/bulk", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "POST", "path": "/api/brands/:brandId/voice-context/retrieve", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "GET", "path": "/api/brands/:brandId/voice-context/stats", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "PUT", "path": "/api/brands/:brandId/voice-context/:contextId", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "DELETE", "path": "/api/brands/:brandId/voice-context/:contextId", "source_path": "apps/TopoloSocialize/apps/api/src/routes/aiAndStrategyRoutes.ts" }, { "method": "ALL", "path": "/api/auth/me", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "ALL", "path": "/api/debug/auth-context", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/posts", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/posts", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/posts/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PUT", "path": "/api/posts/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "DELETE", "path": "/api/posts/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/posts/:id/publish", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/posts/:id/archive", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PATCH", "path": "/api/posts/:id/reschedule", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PATCH", "path": "/api/posts/:id/toggle-pause", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/content-ops/queue", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/content-ops/daily", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/content-ops/events", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/content-ops/deck", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/content-ops/items/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PATCH", "path": "/api/content-ops/items/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/content-ops/items/:id/approve", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/content-ops/items/:id/reject", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/content-ops/items/:id/reschedule", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/content-ops/items/:id/retry", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/campaigns", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/campaigns", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/campaigns/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PUT", "path": "/api/campaigns/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "DELETE", "path": "/api/campaigns/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/campaigns/:id/schedule", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/campaigns/:id/activate", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/campaigns/:id/complete", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/campaigns/:id/cancel", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/campaigns/:id/pause", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/campaigns/:id/resume", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/scheduler/process", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/scheduler/status", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/media/upload", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/media/list", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/media/bulk", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/media/tags", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/media/tags", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "DELETE", "path": "/api/media/tags/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/media/collections", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/media/collections", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "DELETE", "path": "/api/media/collections/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/media/:id/metadata", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/media/:id/complete", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/media/metadata", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/campaigns/:id/analytics", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/campaigns/:id/analytics/engine", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/campaigns/:id/analytics/variants/:variantId", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/analytics/summary", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/flags", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/flags", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/flags/me", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/flags/user/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PUT", "path": "/api/flags/:flagId/users/:userId", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "DELETE", "path": "/api/flags/:flagId/users/:userId", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/flags/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PATCH", "path": "/api/flags/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "DELETE", "path": "/api/flags/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/organization", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/organization/accept-invite", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/brands", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/brands", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "DELETE", "path": "/api/workspaces/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/brands/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PUT", "path": "/api/brands/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/brands/:id/members", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/brands/:id/join-requests", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PUT", "path": "/api/join-requests/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "DELETE", "path": "/api/join-requests/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/organizations/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PUT", "path": "/api/organizations/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/organizations/:id/members", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/organizations/:id/members", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "DELETE", "path": "/api/organizations/:id/members/:userId", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PUT", "path": "/api/organizations/:id/members/:userId", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/organizations/:id/invites", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "DELETE", "path": "/api/organizations/:id/invites/:inviteId", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/organizations/:id/activity", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/organizations/:id/data", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "DELETE", "path": "/api/organizations/:id/data", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/user/preferences", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PUT", "path": "/api/user/preferences", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "GET", "path": "/api/integrations", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "POST", "path": "/api/integrations/:platform/connect", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PUT", "path": "/api/integrations/linkedin/organization", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PUT", "path": "/api/integrations/linkedin_company/organization", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PUT", "path": "/api/integrations/facebook/page", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "PUT", "path": "/api/integrations/:id/nickname", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "DELETE", "path": "/api/integrations/:id", "source_path": "apps/TopoloSocialize/apps/api/src/routes/authenticatedRoutes.ts" }, { "method": "LITERAL", "path": "/health", "source_path": "apps/TopoloSocialize/apps/scheduler/src/index.ts" }, { "method": "LITERAL", "path": "/stats", "source_path": "apps/TopoloSocialize/apps/scheduler/src/index.ts" } ], "ui_routes": [ { "path": "/feed", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/onboarding", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/dashboard", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/campaigns", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/campaigns/new", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/campaigns/:id", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/campaigns/:id/edit", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/posts", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/posts/new", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/posts/:id", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/posts/:id/edit", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/brands/new", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/calendar", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/analytics", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/billing", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/media", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/ai/generate", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/ai/designer", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/ai/studio", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/ai/library", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/ai/trends", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/ai/suggested", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/ai/feed", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/settings", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/settings/:section", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/referrals", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/admin", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/admin/flags", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/privacy", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/terms", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/design-system", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/pricing", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/brand/:slug", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/invites/accept", "source_path": "apps/TopoloSocialize/apps/web/src/App.tsx" }, { "path": "/settings/integrations", "source_path": "apps/TopoloSocialize/apps/web/src/routes/settings-nav.tsx" }, { "path": "/settings/api-keys", "source_path": "apps/TopoloSocialize/apps/web/src/routes/settings-nav.tsx" }, { "path": "/settings/content-context", "source_path": "apps/TopoloSocialize/apps/web/src/routes/settings-nav.tsx" }, { "path": "/settings/content-strategy", "source_path": "apps/TopoloSocialize/apps/web/src/routes/settings-nav.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "internal/apps/socialize", "applications/socialize" ], "present_paths": [ "internal/apps/socialize", "applications/socialize" ], "missing_paths": [], "human_reference": "/systems/socialize", "machine_reference": "/machine/systems/socialize.json", "action_examples": 173, "action_schemas": 173 }, "source_findings": [] }, "topolo-admin": { "id": "topolo-admin", "name": "Topolo Admin", "slug": "topolo-admin", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloAdmin" ], "source_revisions": [ { "source_path": "apps/TopoloAdmin", "repository": "apps/TopoloAdmin", "revision": "78b98e22ab49d3ed3bbb72420eeb68d4a4264134", "ref": "origin/staging" } ], "source_counts": { "source_files": 154, "test_files": 57, "test_cases": 0, "migration_files": 0, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 1, "mobile_contracts": 1, "notifications": 0, "package_manifests": 3, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloAdmin/topolo.app.json", "service_slug": "topolo-admin", "name": "topolo-admin", "app_id": "app_topolo_admin", "compatibility_date": "2026-04-10", "primary_target": "web", "environments": [ "development", "production", "staging" ], "targets": [ { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/worker.ts", "worker_name": "topolo-admin-api", "subdomain": null, "healthcheck_path": "/api/health", "variable_names": [ "AUTH_API_URL" ], "secret_names": [], "bindings": [] }, { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-admin", "subdomain": "admin", "healthcheck_path": "/api/health", "variable_names": [ "AUTH_API_URL", "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null } ] } ], "notifications": [], "notification_contract": { "source_path": null, "role": "consumer_only", "schema_version": null, "owner_app_id": null, "events": [] }, "actions": [ { "name": "widget.get", "title": "Get Admin widget", "description": "Get the TopoloOne widget summary for Admin.", "method": "GET", "path": "/api/widget", "permission": "dashboard:read", "authorizationMode": "runtime", "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-admin --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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." } } ], "action_coverage": { "status": "ok", "served_routes": 2, "matched_actions": 1, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 1, "configured_exclusions": 0, "configuration_findings": [], "notes": [] }, "runtime_contract_audit": { "status": "verified", "actions": 1, "contracts": 1, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/worker.ts" ], "authorization_sources": [ "apps/api/src/worker.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloAdmin/topolo.mobile-experience.json", "contract": { "version": "2026-07-03", "status": "approved", "mode": "web", "webOnly": true, "appId": "app_topolo_admin", "localizationNamespace": "admin", "fallbackPath": "/dashboard", "notes": "TopoloAdmin is the platform-operator admin console (users, organizations, services, pricing, audit logs, security, bugfix queue). It is a dense, desktop-only management surface with no first-class mobile use case; it deliberately does not ship a native dynamic-app experience. webOnly opts it out of the TopoloOne native shell while keeping it web-accessible." } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "LITERAL", "path": "/api/widget", "source_path": "apps/TopoloAdmin/apps/api/src/widget.ts" }, { "method": "GET", "path": "/api/health", "source_path": "apps/TopoloAdmin/apps/api/src/worker.ts" }, { "method": "GET", "path": "/api/widget", "source_path": "apps/TopoloAdmin/apps/api/src/worker.ts" } ], "ui_routes": [ { "path": "/dashboard", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/users", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/users/add", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/users/:id", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/users/:id/edit", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/organizations", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/organizations/add", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/organizations/:id", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/organizations/:id/edit", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/organizations/:organizationId/services/add", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/organizations/:organizationId/services/:relationshipId", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/organizations/:organizationId/services/:relationshipId/edit", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/services", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/services/add", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/services/:id", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/services/:id/edit", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/developers", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/app-submissions", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/developer-requests", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/support", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/analytics", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/capacity", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/audit-logs", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/audit-logs/:id", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/security", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/security/user", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/settings", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/settings/:section", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/login-experience", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/landing-experience", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/platform-pricing", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/app-pricing", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/bugfix-settings", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/bugfix-queue", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloAdmin/apps/web/src/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/admin", "internal/apps/admin" ], "present_paths": [ "applications/admin", "internal/apps/admin" ], "missing_paths": [], "human_reference": "/systems/topolo-admin", "machine_reference": "/machine/systems/topolo-admin.json", "action_examples": 1, "action_schemas": 1 }, "source_findings": [] }, "topolo-agent": { "id": "topolo-agent", "name": "Agent", "slug": "topolo-agent", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloAgent" ], "source_revisions": [ { "source_path": "apps/TopoloAgent", "repository": "apps/TopoloAgent", "revision": "0b6311b87b46f1890852ff3ec5c3d316f1c5b6bf", "ref": "origin/staging" } ], "source_counts": { "source_files": 141, "test_files": 72, "test_cases": 0, "migration_files": 12, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 65, "mobile_contracts": 1, "notifications": 6, "package_manifests": 3, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloAgent/topolo.app.json", "service_slug": "topolo-agent", "name": "topolo-agent", "app_id": "app_topolo_agent", "compatibility_date": "2026-04-10", "primary_target": null, "environments": [ "development", "production", "staging" ], "targets": [ { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-agent", "subdomain": "agent", "healthcheck_path": null, "variable_names": [ "AUTH_API_URL", "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null } ] }, { "name": "api", "kind": "worker", "directory": "apps/api", "main": "index.ts", "worker_name": "topolo-agent-api", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "account_id", "AGENT_APP_URL", "AGENT_COMPLETION_MODEL", "AGENT_COMPLETION_PROVIDER", "CLOUDFLARE_ACCOUNT_ID", "ENVIRONMENT", "NEXUS_GATEWAY_URL", "NEXUS_ORGANIZATION_ID", "NODE_ENV", "PUBLIC_ASSISTANT_ORG_SLUGS", "TOPOLO_AUTH_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "AGENT_CORE_DB", "target": null }, { "kind": "d1", "binding": "AGENT_RUNTIME_DB", "target": null }, { "kind": "d1", "binding": "AGENT_KNOWLEDGE_DB", "target": null }, { "kind": "d1", "binding": "AGENT_EVENTS_DB", "target": null }, { "kind": "r2", "binding": "AGENT_LOGS", "target": null }, { "kind": "vectorize", "binding": "KNOWLEDGE_VECTOR", "target": null }, { "kind": "durableObjects", "binding": "AgentSession", "target": null } ] } ], "notifications": [ "agent.intake.assigned", "agent.monitor.alert_triggered", "agent.report.ready", "agent.workflow.approval_requested", "agent.workflow.run_completed", "agent.workflow.run_failed" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_agent", "events": [ { "type": "agent.intake.assigned", "version": 1, "description": "Agent recorded the durable intake assigned transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "intake_id", "assigned_user_id" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "intake_id": { "type": "string", "minLength": 1 }, "assigned_user_id": { "type": "string", "minLength": 1 } }, "additionalProperties": true }, "examples": [ { "title": "Intake assigned: Acme bootstrap", "body": "A new Agent intake is ready for you to complete.", "object_id": "intake_123", "occurred_at": "2026-07-19T00:00:00.000Z", "intake_id": "intake_123", "assigned_user_id": "user_123" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-agent:intake-assigned:" }, "sensitiveFields": [] }, { "type": "agent.monitor.alert_triggered", "version": 1, "description": "A completed monitor run produced a medium- or high-severity signal requiring review.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "examples": [ { "title": "Pipeline watch needs attention", "body": "Two deals need attention.", "object_id": "monitor_run_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-agent:monitor-alert:" }, "sensitiveFields": [] }, { "type": "agent.report.ready", "version": 1, "description": "A persisted Agent report reached ready state after a monitor run completed.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "examples": [ { "title": "Pipeline watch report", "body": "Two deals need attention.", "object_id": "report_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-agent:report-ready:" }, "sensitiveFields": [] }, { "type": "agent.workflow.approval_requested", "version": 1, "description": "A workflow paused for an explicit approval.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "thread_key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "A workflow paused for an explicit approval.", "body": "Open the owning app to review this event.", "object_id": "object_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-agent:approval:" }, "sensitiveFields": [] }, { "type": "agent.workflow.run_completed", "version": 1, "description": "A persisted workflow run reached completed state and its output is ready to review.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "examples": [ { "title": "Workflow completed: Launch workflow", "body": "The workflow completed successfully and its output is ready to review.", "object_id": "workflow_run_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-agent:workflow-completed:" }, "sensitiveFields": [] }, { "type": "agent.workflow.run_failed", "version": 1, "description": "A workflow run failed and needs attention.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "thread_key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "A workflow run failed and needs attention.", "body": "Open the owning app to review this event.", "object_id": "object_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-agent:workflow-failed:" }, "sensitiveFields": [] } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "workspace:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "agents.list", "title": "List agents", "description": "List configured workspace agents.", "method": "GET", "path": "/api/agents", "permission": "agents:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List agents.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/agents", "body": null }, "effects": "Reads state through GET /api/agents without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/agents", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "agents.create", "title": "Create agent", "description": "Create a workspace agent.", "method": "POST", "path": "/api/agents", "permission": "agents:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "status": { "type": "string" }, "model": { "type": "string" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "templateId": { "type": "string" }, "template_id": { "type": "string" }, "accountableUserId": { "type": "string" }, "accountable_user_id": { "type": "string" }, "executorType": { "type": "string" }, "executor_type": { "type": "string" }, "policyId": { "type": "string" }, "policy_id": { "type": "string" }, "serviceGrants": { "type": "array", "items": {} }, "service_grants": { "type": "array", "items": {} } }, "required": [ "name", "role" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create agent.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "name": "example", "role": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/agents", "body": { "name": "example", "role": "example" } }, "effects": "May change state through POST /api/agents. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/agents", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workflows.list", "toolName": "list_workflow_runs", "title": "List workflows", "description": "List agent workflows.", "method": "GET", "path": "/api/workflows", "permission": "workflows:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List workflows.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workflows", "body": null }, "effects": "Reads state through GET /api/workflows without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workflows", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workflows.run", "title": "Run workflow", "description": "Run an agent workflow by id.", "method": "POST", "path": "/api/workflows/{workflowId}/run", "permission": "runs:invoke", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workflowId": { "type": "string", "minLength": 1 } }, "required": [ "workflowId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Run workflow.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workflowId": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workflows/example/run", "body": { "workflowId": "example" } }, "effects": "May change state through POST /api/workflows/{workflowId}/run. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workflows/*/run", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "approvals.list", "title": "List approvals", "description": "List pending agent approvals.", "method": "GET", "path": "/api/approvals", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List approvals.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/approvals", "body": null }, "effects": "Reads state through GET /api/approvals without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/approvals", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "approvals.get", "title": "Get approval", "description": "Get one approval request in the current organization.", "method": "GET", "path": "/api/approvals/{id}", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/approvals/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/approvals/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/approvals/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "approvals.respond", "title": "Approvals Respond", "description": "Call POST /api/approvals/{id}/respond.", "method": "POST", "path": "/api/approvals/{id}/respond", "permission": "approvals:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "decision": { "type": "string", "enum": [ "approved", "rejected" ] }, "note": { "type": "string" } }, "required": [ "id", "decision" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Approvals Respond.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "decision": "approved" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/approvals/00000000-0000-4000-8000-000000000000/respond", "body": { "id": "00000000-0000-4000-8000-000000000000", "decision": "approved" } }, "effects": "May change state through POST /api/approvals/{id}/respond. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/approvals/*/respond", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "reports.list", "title": "List reports", "description": "List generated agent reports.", "method": "GET", "path": "/api/reports", "permission": "reports:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List reports.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "limit": 1 }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/reports", "body": null }, "effects": "Reads state through GET /api/reports without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/reports", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "monitors.run", "toolName": "run_monitor", "title": "Run monitor", "description": "Run a configured monitor by id.", "method": "POST", "path": "/api/monitors/{monitorId}/run", "permission": "runs:invoke", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "monitorId": { "type": "string", "minLength": 1 } }, "required": [ "monitorId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Run monitor.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "monitorId": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/monitors/example/run", "body": { "monitorId": "example" } }, "effects": "May change state through POST /api/monitors/{monitorId}/run. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/monitors/*/run", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "threads.list", "title": "List threads", "description": "List agent threads.", "method": "GET", "path": "/api/threads", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List threads.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/threads", "body": null }, "effects": "Reads state through GET /api/threads without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/threads", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "threads.create", "title": "Create thread", "description": "Create an agent thread.", "method": "POST", "path": "/api/threads", "permission": "workspace:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string" }, "appScope": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "threadKind": { "type": "string" }, "appSlug": { "type": "string" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create thread.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "title": "example", "appScope": [ "example" ], "threadKind": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/threads", "body": { "title": "example", "appScope": [ "example" ], "threadKind": "example" } }, "effects": "May change state through POST /api/threads. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/threads", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "agents.get", "title": "Agents Get", "description": "Call GET /api/agents/{id}.", "method": "GET", "path": "/api/agents/{id}", "permission": "agents:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Agents Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/agents/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/agents/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/agents/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "agents.update", "title": "Agents Update", "description": "Call PATCH /api/agents/{id}.", "method": "PATCH", "path": "/api/agents/{id}", "permission": "agents:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "role": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "model": { "type": "string" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "accountableUserId": { "type": "string" }, "accountable_user_id": { "type": "string" }, "executorType": { "type": "string" }, "executor_type": { "type": "string" }, "policyId": { "type": "string" }, "policy_id": { "type": "string" }, "serviceGrants": { "type": "array", "items": {} }, "service_grants": { "type": "array", "items": {} } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Agents Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/agents/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PATCH /api/agents/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/agents/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "agents.runs.list", "title": "Agents Runs List", "description": "Call GET /api/agents/{id}/runs.", "method": "GET", "path": "/api/agents/{id}/runs", "permission": "agents:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Agents Runs List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/agents/00000000-0000-4000-8000-000000000000/runs", "body": null }, "effects": "Reads state through GET /api/agents/{id}/runs without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/agents/*/runs", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "agents.runs.create", "title": "Agents Runs Create", "description": "Call POST /api/agents/{id}/runs.", "method": "POST", "path": "/api/agents/{id}/runs", "permission": "runs:invoke", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "output": { "type": "string" }, "duration_ms": { "type": "number" }, "log": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Agents Runs Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/agents/00000000-0000-4000-8000-000000000000/runs", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/agents/{id}/runs. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/agents/*/runs", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "artifacts.list", "title": "Artifacts List", "description": "Call GET /api/artifacts.", "method": "GET", "path": "/api/artifacts", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Artifacts List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "limit": 1 }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/artifacts", "body": null }, "effects": "Reads state through GET /api/artifacts without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/artifacts", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "connectors.list", "title": "Connectors List", "description": "Call GET /api/connectors.", "method": "GET", "path": "/api/connectors", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Connectors List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/connectors", "body": null }, "effects": "Reads state through GET /api/connectors without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/connectors", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "connectors.get", "title": "Connectors Get", "description": "Call GET /api/connectors/{id}.", "method": "GET", "path": "/api/connectors/{id}", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Connectors Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/connectors/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/connectors/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/connectors/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "inbox.list", "title": "Inbox List", "description": "Call GET /api/inbox.", "method": "GET", "path": "/api/inbox", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Inbox List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/inbox", "body": null }, "effects": "Reads state through GET /api/inbox without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/inbox", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "intakes.list", "title": "Intakes List", "description": "Call POST /api/intakes.", "method": "POST", "path": "/api/intakes", "permission": "workspace:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string" }, "orgName": { "type": "string" }, "draftProfile": { "type": "object", "properties": { "orgName": { "type": "string" }, "industry": { "type": "string" }, "businessSummary": { "type": "string" }, "targetCustomer": { "type": "string" }, "revenueModel": { "type": "string" }, "primaryGoals": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferredApps": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "brandVoice": { "type": "string" }, "operatorNotes": { "type": "string" } }, "additionalProperties": false }, "industry": { "type": "string" }, "businessSummary": { "type": "string" }, "targetCustomer": { "type": "string" }, "revenueModel": { "type": "string" }, "primaryGoals": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferredApps": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "brandVoice": { "type": "string" }, "operatorNotes": { "type": "string" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Intakes List.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "title": "example", "orgName": "example", "draftProfile": { "orgName": "example", "industry": "example", "businessSummary": "example" } }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/intakes", "body": { "title": "example", "orgName": "example", "draftProfile": { "orgName": "example", "industry": "example", "businessSummary": "example" } } }, "effects": "May change state through POST /api/intakes. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/intakes", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "intakes.get", "title": "Intakes Get", "description": "Call GET /api/intakes/{id}.", "method": "GET", "path": "/api/intakes/{id}", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Intakes Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/intakes/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/intakes/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/intakes/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "intakes.messages.create", "title": "Intakes Messages Create", "description": "Call POST /api/intakes/{id}/messages.", "method": "POST", "path": "/api/intakes/{id}/messages", "permission": "workspace:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "role": { "type": "string", "enum": [ "operator", "assistant", "system" ] }, "content": { "type": "string" }, "currentStep": { "type": "string" }, "draftProfile": { "type": "object", "properties": { "orgName": { "type": "string" }, "industry": { "type": "string" }, "businessSummary": { "type": "string" }, "targetCustomer": { "type": "string" }, "revenueModel": { "type": "string" }, "primaryGoals": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferredApps": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "brandVoice": { "type": "string" }, "operatorNotes": { "type": "string" } }, "additionalProperties": false } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Intakes Messages Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/intakes/00000000-0000-4000-8000-000000000000/messages", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/intakes/{id}/messages. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/intakes/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "intakes.complete", "title": "Intakes Complete", "description": "Call POST /api/intakes/{id}/complete.", "method": "POST", "path": "/api/intakes/{id}/complete", "permission": "workspace:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "profile": { "type": "object", "properties": { "orgName": { "type": "string" }, "industry": { "type": "string" }, "businessSummary": { "type": "string" }, "targetCustomer": { "type": "string" }, "revenueModel": { "type": "string" }, "primaryGoals": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferredApps": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "brandVoice": { "type": "string" }, "operatorNotes": { "type": "string" } }, "additionalProperties": false } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Intakes Complete.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/intakes/00000000-0000-4000-8000-000000000000/complete", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/intakes/{id}/complete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/intakes/*/complete", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "monitors.list", "toolName": "list_monitors", "title": "Monitors List", "description": "Call GET /api/monitors.", "method": "GET", "path": "/api/monitors", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Monitors List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/monitors", "body": null }, "effects": "Reads state through GET /api/monitors without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/monitors", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "person_profiles.list", "title": "Person Profiles List", "description": "Call GET /api/person-profiles.", "method": "GET", "path": "/api/person-profiles", "permission": "knowledge:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "workspace" ] }, "includeArchived": { "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Person Profiles List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "visibility": "private", "includeArchived": "true" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/person-profiles", "body": null }, "effects": "Reads state through GET /api/person-profiles without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/person-profiles", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "person_profiles.create", "title": "Person Profiles Create", "description": "Call POST /api/person-profiles.", "method": "POST", "path": "/api/person-profiles", "permission": "knowledge:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subjectUserId": { "type": "string" }, "ownerUserId": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "workspace" ] }, "linkedPersonaId": { "type": "string" }, "linkedAgentId": { "type": "string" }, "voiceProfileId": { "type": "string" }, "writingStyle": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "speakingStyle": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "personaRules": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "usagePolicy": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "authorizationEvidence": { "type": "array", "items": {} }, "displayName": { "type": "string", "minLength": 1 } }, "required": [ "displayName" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Person Profiles Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "displayName": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/person-profiles", "body": { "displayName": "example" } }, "effects": "May change state through POST /api/person-profiles. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/person-profiles", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "person_profiles.get", "title": "Person Profiles Get", "description": "Call GET /api/person-profiles/{id}.", "method": "GET", "path": "/api/person-profiles/{id}", "permission": "knowledge:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Person Profiles Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/person-profiles/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/person-profiles/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/person-profiles/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "person_profiles.update", "title": "Person Profiles Update", "description": "Call PATCH /api/person-profiles/{id}.", "method": "PATCH", "path": "/api/person-profiles/{id}", "permission": "knowledge:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "displayName": { "type": "string" }, "subjectUserId": { "type": "string" }, "ownerUserId": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "workspace" ] }, "linkedPersonaId": { "type": "string" }, "linkedAgentId": { "type": "string" }, "voiceProfileId": { "type": "string" }, "writingStyle": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "speakingStyle": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "personaRules": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "usagePolicy": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "authorizationEvidence": { "type": "array", "items": {} } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Person Profiles Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/person-profiles/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PATCH /api/person-profiles/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/person-profiles/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "person_profiles.delete", "title": "Person Profiles Delete", "description": "Call DELETE /api/person-profiles/{id}.", "method": "DELETE", "path": "/api/person-profiles/{id}", "permission": "knowledge:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Person Profiles Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/person-profiles/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/person-profiles/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/person-profiles/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "person_profiles.sources.create", "title": "Person Profiles Sources Create", "description": "Call POST /api/person-profiles/{id}/sources.", "method": "POST", "path": "/api/person-profiles/{id}/sources", "permission": "knowledge:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sourceUrl": { "type": "string" }, "knowledgeDocumentId": { "type": "string" }, "authorizationEvidenceId": { "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "id": { "type": "string", "minLength": 1 }, "sourceKind": { "type": "string", "minLength": 1 }, "sourceLabel": { "type": "string", "minLength": 1 } }, "required": [ "id", "sourceKind", "sourceLabel" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Person Profiles Sources Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "sourceKind": "example", "sourceLabel": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/person-profiles/00000000-0000-4000-8000-000000000000/sources", "body": { "id": "00000000-0000-4000-8000-000000000000", "sourceKind": "example", "sourceLabel": "example" } }, "effects": "May change state through POST /api/person-profiles/{id}/sources. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/person-profiles/*/sources", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "person_profiles.style_snapshots.create", "title": "Person Profiles Style Snapshots Create", "description": "Call POST /api/person-profiles/{id}/style-snapshots.", "method": "POST", "path": "/api/person-profiles/{id}/style-snapshots", "permission": "knowledge:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "facet": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "minLength": 1 }, "styleRules": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "confidence": { "type": "number" }, "sourceCount": { "type": "number" } }, "required": [ "id", "facet", "summary" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Person Profiles Style Snapshots Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "facet": "example", "summary": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/person-profiles/00000000-0000-4000-8000-000000000000/style-snapshots", "body": { "id": "00000000-0000-4000-8000-000000000000", "facet": "example", "summary": "example" } }, "effects": "May change state through POST /api/person-profiles/{id}/style-snapshots. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/person-profiles/*/style-snapshots", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "person_profiles.preview", "title": "Person Profiles Preview", "description": "Call POST /api/person-profiles/{id}/preview.", "method": "POST", "path": "/api/person-profiles/{id}/preview", "permission": "knowledge:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "brief": { "type": "string" }, "prompt": { "type": "string" }, "mode": { "type": "string", "enum": [ "email", "chat", "brief", "post" ] }, "audience": { "type": "string" }, "channel": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Person Profiles Preview.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/person-profiles/00000000-0000-4000-8000-000000000000/preview", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/person-profiles/{id}/preview. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/person-profiles/*/preview", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "personas.list", "title": "Personas List", "description": "Call GET /api/personas.", "method": "GET", "path": "/api/personas", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "workspace" ] }, "includeArchived": { "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Personas List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "visibility": "private", "includeArchived": "true" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/personas", "body": null }, "effects": "Reads state through GET /api/personas without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/personas", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "personas.create", "title": "Personas Create", "description": "Call POST /api/personas.", "method": "POST", "path": "/api/personas", "permission": "workspace:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "persona": { "type": "string" }, "pointOfView": { "type": "string", "enum": [ "first", "third" ] }, "point_of_view": { "type": "string", "enum": [ "first", "third" ] }, "targetAudience": { "type": "string" }, "target_audience": { "type": "string" }, "tone": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "voice": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "avatar": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "modelRouting": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "model_routing": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "visibility": { "type": "string", "enum": [ "private", "workspace" ] }, "isDefault": { "type": "boolean" }, "is_default": { "type": "boolean" }, "isArchived": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "doList": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "do_list": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "dontList": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "dont_list": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "bannedPhrases": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "banned_phrases": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferredVocabulary": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferred_vocabulary": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] } }, "required": [ "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Personas Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "name": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/personas", "body": { "name": "example" } }, "effects": "May change state through POST /api/personas. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/personas", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "personas.get", "title": "Personas Get", "description": "Call GET /api/personas/{id}.", "method": "GET", "path": "/api/personas/{id}", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Personas Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/personas/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/personas/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/personas/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "personas.update", "title": "Personas Update", "description": "Call PATCH /api/personas/{id}.", "method": "PATCH", "path": "/api/personas/{id}", "permission": "workspace:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "persona": { "type": "string" }, "pointOfView": { "type": "string", "enum": [ "first", "third" ] }, "point_of_view": { "type": "string", "enum": [ "first", "third" ] }, "targetAudience": { "type": "string" }, "target_audience": { "type": "string" }, "tone": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "voice": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "avatar": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "modelRouting": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "model_routing": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "visibility": { "type": "string", "enum": [ "private", "workspace" ] }, "isDefault": { "type": "boolean" }, "is_default": { "type": "boolean" }, "isArchived": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "doList": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "do_list": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "dontList": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "dont_list": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "bannedPhrases": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "banned_phrases": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferredVocabulary": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferred_vocabulary": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Personas Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/personas/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PATCH /api/personas/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/personas/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "personas.delete", "title": "Personas Delete", "description": "Call DELETE /api/personas/{id}.", "method": "DELETE", "path": "/api/personas/{id}", "permission": "workspace:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Personas Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/personas/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/personas/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/personas/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "personas.set_default", "title": "Personas Set Default", "description": "Call POST /api/personas/{id}/default.", "method": "POST", "path": "/api/personas/{id}/default", "permission": "workspace:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Personas Set Default.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/personas/00000000-0000-4000-8000-000000000000/default", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/personas/{id}/default. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/personas/*/default", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "agent_thread.get", "title": "Agent Thread Get", "description": "Call GET /api/agent-thread.", "method": "GET", "path": "/api/agent-thread", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Agent Thread Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/agent-thread", "body": null }, "effects": "Reads state through GET /api/agent-thread without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/agent-thread", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "agent_sessions.state", "title": "Get agent session state", "description": "Get the transcript and pending approval state for an agent session.", "method": "GET", "path": "/api/agent-session/{threadId}", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 } }, "required": [ "threadId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "threadId": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/agent-session/example", "body": null }, "effects": "Reads state through GET /api/agent-session/{threadId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/agent-session/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "agent_sessions.message", "title": "Send agent session message", "description": "Run a message turn in a workspace-scoped agent session.", "method": "POST", "path": "/api/agent-session/{threadId}", "permission": "workspace:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "message" }, "content": { "type": "string", "minLength": 1 }, "personaId": { "type": "string", "minLength": 1 } }, "required": [ "threadId", "type", "content" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "threadId": "example", "type": "message", "content": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/agent-session/example", "body": { "threadId": "example", "type": "message", "content": "example" } }, "effects": "May change state through POST /api/agent-session/{threadId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/agent-session/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "agent_sessions.approve", "title": "Resolve agent session approval", "description": "Approve or reject a pending agent-session tool call.", "method": "POST", "path": "/api/agent-session/{threadId}", "permission": "workspace:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "approve" }, "approvalId": { "type": "string", "minLength": 1 }, "decision": { "type": "string", "enum": [ "approve", "reject" ] } }, "required": [ "threadId", "type", "approvalId", "decision" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "threadId": "example", "type": "approve", "approvalId": "example", "decision": "approve" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/agent-session/example", "body": { "threadId": "example", "type": "approve", "approvalId": "example", "decision": "approve" } }, "effects": "May change state through POST /api/agent-session/{threadId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/agent-session/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "agent_thread.create", "title": "Agent Thread Create", "description": "Call POST /api/agent-thread.", "method": "POST", "path": "/api/agent-thread", "permission": "workspace:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string", "minLength": 1 } }, "required": [ "content" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Agent Thread Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "content": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/agent-thread", "body": { "content": "example" } }, "effects": "May change state through POST /api/agent-thread. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/agent-thread", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "agent_thread.stream", "title": "Agent Thread Stream", "description": "Call POST /api/agent-thread/stream.", "method": "POST", "path": "/api/agent-thread/stream", "permission": "runs:invoke", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string", "minLength": 1 } }, "required": [ "content" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Agent Thread Stream.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "content": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/agent-thread/stream", "body": { "content": "example" } }, "effects": "May change state through POST /api/agent-thread/stream. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/agent-thread/stream", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "threads.get", "title": "Threads Get", "description": "Call GET /api/threads/{id}.", "method": "GET", "path": "/api/threads/{id}", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Threads Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/threads/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/threads/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/threads/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "threads.update", "title": "Threads Update", "description": "Call POST /api/threads/{id}.", "method": "POST", "path": "/api/threads/{id}", "permission": "workspace:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 } }, "required": [ "id", "content" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Threads Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "content": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/threads/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000", "content": "example" } }, "effects": "May change state through POST /api/threads/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/threads/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "threads.stream", "title": "Threads Stream", "description": "Call POST /api/threads/{id}/stream.", "method": "POST", "path": "/api/threads/{id}/stream", "permission": "runs:invoke", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 } }, "required": [ "id", "content" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Threads Stream.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "content": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/threads/00000000-0000-4000-8000-000000000000/stream", "body": { "id": "00000000-0000-4000-8000-000000000000", "content": "example" } }, "effects": "May change state through POST /api/threads/{id}/stream. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/threads/*/stream", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "threads.import_website", "title": "Threads Import Website", "description": "Call POST /api/threads/{id}/import-website.", "method": "POST", "path": "/api/threads/{id}/import-website", "permission": "knowledge:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "url": { "type": "string", "minLength": 1 } }, "required": [ "id", "url" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Threads Import Website.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "url": "https://example.com" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/threads/00000000-0000-4000-8000-000000000000/import-website", "body": { "id": "00000000-0000-4000-8000-000000000000", "url": "https://example.com" } }, "effects": "May change state through POST /api/threads/{id}/import-website. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/threads/*/import-website", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "threads.reset_onboarding", "title": "Threads Reset Onboarding", "description": "Call POST /api/threads/{id}/reset-onboarding.", "method": "POST", "path": "/api/threads/{id}/reset-onboarding", "permission": "workspace:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Threads Reset Onboarding.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/threads/00000000-0000-4000-8000-000000000000/reset-onboarding", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/threads/{id}/reset-onboarding. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/threads/*/reset-onboarding", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "threads.attachments.list", "title": "Threads Attachments List", "description": "Call GET /api/threads/{id}/attachments.", "method": "GET", "path": "/api/threads/{id}/attachments", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Threads Attachments List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/threads/00000000-0000-4000-8000-000000000000/attachments", "body": null }, "effects": "Reads state through GET /api/threads/{id}/attachments without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/threads/*/attachments", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "threads.attachments.create", "title": "Threads Attachments Create", "description": "Call POST /api/threads/{id}/attachments.", "method": "POST", "path": "/api/threads/{id}/attachments", "permission": "workspace:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string" }, "contentType": { "type": "string" }, "fileName": { "type": "string" }, "scope": { "type": "string", "enum": [ "thread", "global" ] } }, "required": [ "id", "contentBase64", "contentType", "fileName" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Threads Attachments Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "upload": { "profile": "inline-base64", "contentField": "contentBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 5242880, "acceptedContentTypes": [ "*/*" ] } }, "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "contentBase64": "example", "contentType": "example", "fileName": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/threads/00000000-0000-4000-8000-000000000000/attachments", "body": { "id": "00000000-0000-4000-8000-000000000000", "contentBase64": "example", "contentType": "example", "fileName": "example" } }, "effects": "May change state through POST /api/threads/{id}/attachments. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/threads/*/attachments", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "threads.attachments.download", "title": "Threads Attachments Download", "description": "Call GET /api/threads/{id}/attachments/{attachmentId}/download.", "method": "GET", "path": "/api/threads/{id}/attachments/{attachmentId}/download", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "attachmentId": { "type": "string", "minLength": 1 } }, "required": [ "id", "attachmentId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Threads Attachments Download.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "attachmentId": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/threads/00000000-0000-4000-8000-000000000000/attachments/example/download", "body": null }, "effects": "Reads state through GET /api/threads/{id}/attachments/{attachmentId}/download without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/threads/*/attachments/*/download", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "work_feed.list", "title": "Work Feed List", "description": "Call GET /api/work-feed.", "method": "GET", "path": "/api/work-feed", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Work Feed List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "limit": 1 }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/work-feed", "body": null }, "effects": "Reads state through GET /api/work-feed without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/work-feed", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workflows.get", "title": "Workflows Get", "description": "Call GET /api/workflows/{id}.", "method": "GET", "path": "/api/workflows/{id}", "permission": "workflows:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Workflows Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workflows/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/workflows/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workflows/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workflows.create", "toolName": "create_workflow", "title": "Workflows Create", "description": "Call POST /api/workflows.", "method": "POST", "path": "/api/workflows", "permission": "workflows:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "templateSlug": { "type": "string" }, "autoRun": { "type": "boolean" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Workflows Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "templateSlug": "example", "autoRun": true }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workflows", "body": { "templateSlug": "example", "autoRun": true } }, "effects": "May change state through POST /api/workflows. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workflows", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "Delete workspace", "description": "Delete an empty, non-default Agent workspace.", "method": "DELETE", "path": "/api/workspaces/{workspaceId}", "permission": "workspace:delete", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.export", "title": "Export organization data", "description": "Export organization-authored Agent data across D1 and external storage metadata without provider credentials or binary objects.", "method": "GET", "path": "/api/organizations/{organizationId}/data", "permission": "privacy:read", "readOnly": true, "requiresConfirmation": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "organizationId": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/example/data", "body": null }, "effects": "Reads state through GET /api/organizations/{organizationId}/data without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.erase", "title": "Erase organization data", "description": "Erase organization-authored Agent data after active work is stopped and literal ERASE confirmation is provided.", "method": "DELETE", "path": "/api/organizations/{organizationId}/data", "permission": "privacy:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "organizationId", "confirmation" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "organizationId": "example", "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/example/data", "body": null }, "effects": "May change state through DELETE /api/organizations/{organizationId}/data. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspace.get", "toolName": "get_workspace_summary", "title": "Workspace Get", "description": "Call GET /api/workspace.", "method": "GET", "path": "/api/workspace", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Workspace Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspace", "body": null }, "effects": "Reads state through GET /api/workspace without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspace", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspace.profile.update", "title": "Update workspace profile", "description": "Update the operating profile for the current workspace.", "method": "PATCH", "path": "/api/workspace/profile", "permission": "workspace:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "profile": { "type": "object", "properties": { "orgName": { "type": "string", "minLength": 1 }, "industry": { "type": "string", "minLength": 1 }, "businessSummary": { "type": "string", "minLength": 1 }, "targetCustomer": { "type": "string", "minLength": 1 }, "revenueModel": { "type": "string", "minLength": 1 }, "primaryGoals": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "preferredApps": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "brandVoice": { "type": "string", "minLength": 1 }, "operatorNotes": { "type": "string" } }, "required": [ "orgName", "industry", "businessSummary", "targetCustomer", "revenueModel", "primaryGoals", "preferredApps", "brandVoice" ], "additionalProperties": false } }, "required": [ "profile" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "profile": { "orgName": "example", "industry": "example", "businessSummary": "example", "targetCustomer": "example", "revenueModel": "example", "primaryGoals": [ "example" ], "preferredApps": [ "example" ], "brandVoice": "example" } }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/workspace/profile", "body": { "profile": { "orgName": "example", "industry": "example", "businessSummary": "example", "targetCustomer": "example", "revenueModel": "example", "primaryGoals": [ "example" ], "preferredApps": [ "example" ], "brandVoice": "example" } } }, "effects": "May change state through PATCH /api/workspace/profile. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/workspace/profile", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sdr.leads.ingest", "title": "Ingest SDR lead", "description": "Create or update campaign-scoped SDR readiness state.", "method": "POST", "path": "/api/sdr/ingest", "permission": "workspace:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "leadKey": { "type": "string", "minLength": 1 }, "campaignKey": { "type": "string", "minLength": 1 }, "crmCompanyId": { "type": "string" }, "crmContactId": { "type": "string" }, "organization": { "type": "object", "properties": { "canonicalName": { "type": "string", "minLength": 1 }, "domain": { "type": "string" }, "website": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" }, "address": { "type": "string" }, "linkedinUrl": { "type": "string" }, "industry": { "type": "string" }, "size": { "type": "string" } }, "required": [ "canonicalName" ], "additionalProperties": false }, "contacts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "fullName": { "type": "string" }, "title": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "whatsapp": { "type": "string" }, "linkedinUrl": { "type": "string" }, "externalProfileUrl": { "type": "string" }, "sourceConfidence": { "type": "number" }, "isPrimary": { "type": "boolean" } }, "additionalProperties": false } }, "source": { "type": "object", "properties": { "method": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "url": { "type": "string" }, "query": { "type": "string" }, "market": { "type": "string" }, "discoveredAt": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "method", "provider" ], "additionalProperties": false }, "enrichment": { "type": "object", "properties": { "organizationFacts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "value": {}, "sourceUrl": { "type": "string" }, "confidence": { "type": "number" } }, "required": [ "type", "value" ], "additionalProperties": false } }, "contactFacts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "value": {}, "sourceUrl": { "type": "string" }, "confidence": { "type": "number" } }, "required": [ "type", "value" ], "additionalProperties": false } } }, "additionalProperties": false }, "proposedScores": { "type": "object", "properties": { "icpFitScore": { "type": "number" }, "contactabilityScore": { "type": "number" }, "sourceConfidenceScore": { "type": "number" }, "namedContactScore": { "type": "number" }, "overallOutboundScore": { "type": "number" } }, "additionalProperties": false }, "qualityGate": { "type": "object", "properties": { "status": { "type": "string", "minLength": 1 }, "reason": { "type": "string" } }, "required": [ "status" ], "additionalProperties": false }, "controls": { "type": "object", "properties": { "manualState": { "type": "string", "enum": [ "active", "paused", "stopped" ] } }, "additionalProperties": false }, "lifecycle": { "type": "object", "properties": { "replyReceivedAt": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] }, "lastOutboundAt": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] }, "nextActionAt": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] } }, "additionalProperties": false } }, "required": [ "leadKey", "campaignKey", "organization", "contacts", "source", "enrichment", "proposedScores", "qualityGate" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "leadKey": "example", "campaignKey": "example", "organization": { "canonicalName": "example" }, "contacts": [ { "fullName": "example", "title": "example", "email": "user@example.com" } ], "source": { "method": "example", "provider": "example" }, "enrichment": { "organizationFacts": [ { "type": "example", "value": "example" } ], "contactFacts": [ { "type": "example", "value": "example" } ] }, "proposedScores": { "icpFitScore": 1, "contactabilityScore": 1, "sourceConfidenceScore": 1 }, "qualityGate": { "status": "example" } }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/sdr/ingest", "body": { "leadKey": "example", "campaignKey": "example", "organization": { "canonicalName": "example" }, "contacts": [ { "fullName": "example", "title": "example", "email": "user@example.com" } ], "source": { "method": "example", "provider": "example" }, "enrichment": { "organizationFacts": [ { "type": "example", "value": "example" } ], "contactFacts": [ { "type": "example", "value": "example" } ] }, "proposedScores": { "icpFitScore": 1, "contactabilityScore": 1, "sourceConfidenceScore": 1 }, "qualityGate": { "status": "example" } } }, "effects": "May change state through POST /api/sdr/ingest. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/sdr/ingest", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sdr.leads.outbound_ready", "title": "List outbound-ready SDR leads", "description": "List leads that currently pass campaign, evidence, contactability, and suppression gates.", "method": "GET", "path": "/api/sdr/outbound-ready", "permission": "workspace:read", "readOnly": true, "requiresConfirmation": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "campaign": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 250 } }, "required": [ "campaign" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "campaign": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/sdr/outbound-ready", "body": null }, "effects": "Reads state through GET /api/sdr/outbound-ready without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/sdr/outbound-ready", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sdr.leads.get", "title": "Get SDR lead", "description": "Get one campaign-scoped SDR lead and its current readiness state.", "method": "GET", "path": "/api/sdr/leads/{leadKey}", "permission": "workspace:read", "readOnly": true, "requiresConfirmation": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "leadKey": { "type": "string", "minLength": 1 }, "campaign": { "type": "string", "minLength": 1 } }, "required": [ "leadKey", "campaign" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "leadKey": "example", "campaign": "example" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/sdr/leads/example", "body": null }, "effects": "Reads state through GET /api/sdr/leads/{leadKey} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/sdr/leads/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sdr.leads.events.create", "title": "Record SDR lead event", "description": "Record outbound, reply, pause, stop, or resume state for an SDR lead.", "method": "POST", "path": "/api/sdr/leads/{leadKey}/events", "permission": "workspace:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "leadKey": { "type": "string", "minLength": 1 }, "campaignKey": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "enum": [ "outbound_sent", "reply_received", "paused", "stopped", "resumed" ] }, "channel": { "type": "string" }, "occurredAt": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "nextActionAt": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "leadKey", "campaignKey", "eventType" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "leadKey": "example", "campaignKey": "example", "eventType": "outbound_sent" }, "cli_example": [ "topolo actions --service topolo-agent --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/sdr/leads/example/events", "body": { "leadKey": "example", "campaignKey": "example", "eventType": "outbound_sent" } }, "effects": "May change state through POST /api/sdr/leads/{leadKey}/events. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/sdr/leads/*/events", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 75, "matched_actions": 64, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 11, "configured_exclusions": 5, "configuration_findings": [], "notes": [] }, "runtime_contract_audit": { "status": "verified", "actions": 65, "contracts": 65, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/index.ts" ], "authorization_sources": [ "apps/api/index.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloAgent/topolo.mobile-experience.json", "contract": { "version": "2026-06-29", "status": "approved", "mode": "native_capability", "appId": "app_topolo_agent", "localizationNamespace": "agent", "permissions": [ "agents:read", "workflows:read", "reports:read", "workspace:read" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/agents", "auth": { "audience": "topolo-agent", "scopes": [ "agents:read", "workflows:read", "reports:read", "workspace:read" ] }, "routes": [ { "path": "/agents", "apiPath": "/api/agents", "title": "Agents", "titleKey": "agent.mobile.routes.agents.title", "template": "record.list", "dataSource": "agent.agents.list", "detailRoute": "/agents/:id" }, { "path": "/agents/:id", "apiPath": "/api/agents/:id", "title": "Agent", "titleKey": "agent.mobile.routes.agentDetail.title", "template": "record.detail", "dataSource": "agent.agents.detail" }, { "path": "/workflows", "apiPath": "/api/workflows", "title": "Workflows", "titleKey": "agent.mobile.routes.workflows.title", "template": "record.list", "dataSource": "agent.workflows.list", "detailRoute": "/workflows/:id" }, { "path": "/workflows/:id", "apiPath": "/api/workflows/:id", "title": "Workflow", "titleKey": "agent.mobile.routes.workflowDetail.title", "template": "record.detail", "dataSource": "agent.workflows.detail" }, { "path": "/approvals", "apiPath": "/api/approvals", "title": "Approvals", "titleKey": "agent.mobile.routes.approvals.title", "template": "record.list", "dataSource": "agent.approvals.list", "detailRoute": "/approvals/:id" }, { "path": "/approvals/:id", "apiPath": "/api/approvals/:id", "title": "Approval", "titleKey": "agent.mobile.routes.approvals.title", "template": "record.detail", "dataSource": "agent.approvals.detail" }, { "path": "/threads", "apiPath": "/api/threads", "title": "Threads", "titleKey": "agent.nav.threads", "template": "record.list", "dataSource": "agent.threads.list", "detailRoute": "/threads/:id" }, { "path": "/threads/:id", "apiPath": "/api/threads/:id", "title": "Thread", "titleKey": "agent.mobile.routes.threadDetail.title", "template": "record.detail", "dataSource": "agent.threads.detail" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "ALL", "path": "/health", "source_path": "apps/TopoloAgent/apps/api/index.ts" }, { "method": "ALL", "path": "/api/health", "source_path": "apps/TopoloAgent/apps/api/index.ts" }, { "method": "ALL", "path": "/api/app-identity", "source_path": "apps/TopoloAgent/apps/api/index.ts" }, { "method": "GET", "path": "/api/public/assistant-profile", "source_path": "apps/TopoloAgent/apps/api/index.ts" }, { "method": "ALL", "path": "/api/public/assistant-profile", "source_path": "apps/TopoloAgent/apps/api/index.ts" }, { "method": "POST", "path": "/api/s2s/agent-session/invoke", "source_path": "apps/TopoloAgent/apps/api/index.ts" }, { "method": "ALL", "path": "/api/s2s/agent-session/invoke", "source_path": "apps/TopoloAgent/apps/api/index.ts" }, { "method": "POST", "path": "/api/public/chat", "source_path": "apps/TopoloAgent/apps/api/index.ts" }, { "method": "ALL", "path": "/api/public/chat", "source_path": "apps/TopoloAgent/apps/api/index.ts" }, { "method": "GET", "path": "/api/widget", "source_path": "apps/TopoloAgent/apps/api/index.ts" }, { "method": "ALL", "path": "/api/widget", "source_path": "apps/TopoloAgent/apps/api/index.ts" }, { "method": "GET", "path": "/api/agent-session/:threadId", "source_path": "apps/TopoloAgent/apps/api/index.ts" }, { "method": "POST", "path": "/api/agent-session/:threadId", "source_path": "apps/TopoloAgent/apps/api/index.ts" }, { "method": "ALL", "path": "/api/agent-session/:threadId", "source_path": "apps/TopoloAgent/apps/api/index.ts" } ], "ui_routes": [ { "path": "/today", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/copilot", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/threads", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/work", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/inbox", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/work-feed", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/reports", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/artifacts", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/runs", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/people", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/personas", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/person-profiles", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/memory", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/settings", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/settings/:section", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloAgent/apps/web/src/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "internal/apps/agent", "applications/agent" ], "present_paths": [ "internal/apps/agent", "applications/agent" ], "missing_paths": [], "human_reference": "/systems/topolo-agent", "machine_reference": "/machine/systems/topolo-agent.json", "action_examples": 65, "action_schemas": 65 }, "source_findings": [] }, "topolo-auth": { "id": "topolo-auth", "name": "Topolo Auth", "slug": "topolo-auth", "kind": "service", "visibility": "public", "repo_paths": [ "topolo-platform/core/TopoloAuth", "topolo-platform/packages/topolo-auth-client", "topolo-platform/packages/topolo-auth-middleware", "topolo-platform/core/TopoloAuth/packages/topolo_auth_flutter" ], "source_revisions": [ { "source_path": "topolo-platform/core/TopoloAuth", "repository": "topolo-platform", "revision": "515376de81efed9734741b2a1d691c8195243073", "ref": "origin/staging" }, { "source_path": "topolo-platform/packages/topolo-auth-client", "repository": "topolo-platform", "revision": "515376de81efed9734741b2a1d691c8195243073", "ref": "origin/staging" }, { "source_path": "topolo-platform/packages/topolo-auth-middleware", "repository": "topolo-platform", "revision": "515376de81efed9734741b2a1d691c8195243073", "ref": "origin/staging" }, { "source_path": "topolo-platform/core/TopoloAuth/packages/topolo_auth_flutter", "repository": "topolo-platform", "revision": "515376de81efed9734741b2a1d691c8195243073", "ref": "origin/staging" } ], "source_counts": { "source_files": 450, "test_files": 307, "test_cases": 0, "migration_files": 54, "database_tables": 0, "manifests": 1, "deploy_targets": 1, "actions": 181, "mobile_contracts": 0, "notifications": 22, "package_manifests": 3, "deployment_configs": 0 }, "manifests": [ { "source_path": "topolo-platform/core/TopoloAuth/topolo.app.json", "service_slug": "topolo-auth", "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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-auth --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": [] } } ], "mobile_contracts": [], "package_manifests": [], "deployment_configs": [], "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" } ], "ui_routes": [], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/auth", "reference/api/topolo-auth", "internal/platform/identity-access-entitlements", "internal/platform/application-entry-and-admission", "internal/platform/workspace-ownership-access", "internal/platform/auth-and-identity", "internal/platform/ai-workforce-credentials", "internal/platform/topolo-auth-flutter-sdk", "internal/platform/notification-preferences", "internal/apps/topolo-auth", "internal/platform/data-privacy-and-encryption" ], "present_paths": [ "applications/auth", "reference/api/topolo-auth", "internal/platform/identity-access-entitlements", "internal/platform/application-entry-and-admission", "internal/platform/workspace-ownership-access", "internal/platform/auth-and-identity", "internal/platform/ai-workforce-credentials", "internal/platform/topolo-auth-flutter-sdk", "internal/platform/notification-preferences", "internal/apps/topolo-auth", "internal/platform/data-privacy-and-encryption" ], "missing_paths": [], "human_reference": "/systems/topolo-auth", "machine_reference": "/machine/systems/topolo-auth.json", "action_examples": 181, "action_schemas": 181 }, "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" } ] } ] }, "topolo-blog": { "id": "topolo-blog", "name": "Blog", "slug": "topolo-blog", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloBlog" ], "source_revisions": [ { "source_path": "apps/TopoloBlog", "repository": "apps/TopoloBlog", "revision": "ea26b09a5159a13506f1bc6b020273fb1a9396a1", "ref": "origin/staging" } ], "source_counts": { "source_files": 68, "test_files": 31, "test_cases": 0, "migration_files": 4, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 42, "mobile_contracts": 0, "notifications": 1, "package_manifests": 1, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloBlog/topolo.app.json", "service_slug": "topolo-blog", "name": "topolo-blog", "app_id": "app_topolo_blog", "compatibility_date": "2026-05-05", "primary_target": null, "environments": [ "development", "production", "staging" ], "targets": [ { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/worker.ts", "worker_name": "topolo-blog-api", "subdomain": null, "healthcheck_path": "/api/health", "variable_names": [ "AUTH_BASE_URL", "INSIGHTS_API_URL", "INSIGHTS_WORKSPACE_ID", "NEXUS_GATEWAY_URL", "TOPOLO_NOTIFY_URL", "TOPOLO_ONE_REVALIDATE_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "BLOG_CORE_DB", "target": null }, { "kind": "r2", "binding": "APP_ASSETS", "target": null }, { "kind": "workflows", "binding": "APP_WORKFLOW", "target": null } ] }, { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-blog", "subdomain": "blog", "healthcheck_path": "/api/health", "variable_names": [ "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null } ] } ], "notifications": [ "blog.article.published" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_blog", "events": [ { "type": "blog.article.published", "version": 1, "description": "A persisted article revision became publicly readable from a TopoloBlog publication.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "article_id", "publication_key", "canonical_url", "revision_number" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "priority": { "enum": [ "low", "normal", "high", "urgent" ] }, "severity": { "enum": [ "info", "success", "warning", "critical" ] }, "category": { "type": "string" }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "article_id": { "type": "string", "minLength": 1 }, "publication_key": { "type": "string", "minLength": 1 }, "canonical_url": { "type": "string", "format": "uri" }, "revision_number": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "examples": [ { "title": "Published: Agent-native business software", "body": "The article is now publicly available.", "surface": "notification", "priority": "normal", "severity": "success", "category": "blog", "object_type": "blog_article", "object_id": "article_agent_native_business_software", "cta_url": "https://topolo.io/blog/agent-native-business-software", "cta_label": "View article", "occurred_at": "2026-08-09T00:00:00.000Z", "article_id": "article_agent_native_business_software", "publication_key": "topolo", "canonical_url": "https://topolo.io/blog/agent-native-business-software", "revision_number": 3 } ], "dataClassification": "public", "recipients": { "modes": [ "workspace_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^blog:article:published:" }, "sensitiveFields": [] } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloBlog widget summary.", "method": "GET", "path": "/api/widget", "permission": "workspace:read", "authorizationMode": "static", "readOnly": true, "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" }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "snapshot": { "type": "object", "properties": { "summary": { "type": "string" } }, "required": [ "summary" ], "additionalProperties": {} }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "link": { "type": "string" }, "primary": { "type": "boolean" } }, "required": [ "id", "label", "link" ], "additionalProperties": false } }, "appId": { "type": "string" }, "serviceName": { "type": "string" }, "lastUpdated": { "type": "string" } }, "required": [ "type", "snapshot", "actions", "appId", "serviceName", "lastUpdated" ], "additionalProperties": {} } } }, "required": [ "success", "widgets" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=widget.get", "resource": { "kind": "widget", "idPath": "$.id" }, "effects": [ "Reads widget data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for widget.get." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/widget", "body": null }, "effects": "Reads widget data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=widget.get", "resource": { "kind": "widget", "idPath": "$.id" }, "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 workspace bootstrap", "description": "Get the signed TopoloBlog workspace bootstrap payload.", "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": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": {} }, "organization": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "user", "organization" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=workspace.bootstrap", "resource": { "kind": "workspace", "idPath": "$.id" }, "effects": [ "Reads workspace data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for workspace.bootstrap." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/bootstrap", "body": null }, "effects": "Reads workspace data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=workspace.bootstrap", "resource": { "kind": "workspace", "idPath": "$.id" }, "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": "overview.get", "title": "Get publishing overview", "description": "Get publishing counts, upcoming releases, and recent editorial work.", "method": "GET", "path": "/api/overview", "permission": "workspace:read", "authorizationMode": "static", "readOnly": true, "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": { "overview": { "type": "object", "properties": { "counts": { "type": "object", "properties": { "draft": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "scheduled": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "published": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "media": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "publications": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "draft", "scheduled", "published", "media", "publications" ], "additionalProperties": false }, "upcoming": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "recent": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "counts", "upcoming", "recent" ], "additionalProperties": false } }, "required": [ "overview" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=overview.get", "resource": { "kind": "workspace", "idPath": "$.id" }, "effects": [ "Reads workspace data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for overview.get." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/overview", "body": null }, "effects": "Reads workspace data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=overview.get", "resource": { "kind": "workspace", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/overview", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "analytics.overview", "title": "Get readership analytics", "description": "Get the shared Insights readership overview for this editorial workspace.", "method": "GET", "path": "/api/analytics", "permission": "workspace:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 90 } }, "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "data" ], "additionalProperties": {} }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=analytics.overview", "resource": { "kind": "workspace", "idPath": "$.id" }, "effects": [ "Reads workspace data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": { "days": 30 }, "expected": "A response matching the published outputSchema for analytics.overview." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "days": 30 }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/analytics", "body": null }, "effects": "Reads workspace data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=analytics.overview", "resource": { "kind": "workspace", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/analytics", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.list", "title": "List articles", "description": "Search, filter, sort, and paginate articles in the selected editorial workspace.", "method": "GET", "path": "/api/articles", "permission": "workspace:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "maxLength": 160 }, "status": { "type": "string", "enum": [ "all", "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "all", "draft", "in_review", "changes_requested", "approved" ] }, "sort": { "type": "string", "enum": [ "updatedAt", "title", "publishedAt" ] }, "order": { "type": "string", "enum": [ "asc", "desc" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "articles", "total", "nextCursor" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.list", "resource": { "kind": "article", "idPath": "$.items[].id" }, "effects": [ "Reads article data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for articles.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/articles", "body": null }, "effects": "Reads article data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.list", "resource": { "kind": "article", "idPath": "$.items[].id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/articles", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.preview", "title": "Preview article", "description": "Render an unsaved article draft to the same HTML used by the published reader surface.", "method": "POST", "path": "/api/articles/preview", "permission": "workspace:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Article headline; renders as the page H1 and seeds the slug when slug is omitted." }, "slug": { "description": "URL path segment. Omit to derive it from the title.", "type": "string", "maxLength": 120 }, "publicationId": { "description": "Target publication id from publications.list. Omit to use the workspace default publication.", "type": "string", "minLength": 1 }, "excerpt": { "type": "string", "maxLength": 320 }, "body": { "description": "Ordered article content as typed blocks (paragraph, heading, list, image, quote, divider, code, callout). Text fields accept inline markdown: **bold**, *italic*, `code`, [label](https://…).", "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "maxItems": 12, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 48 } }, "seriesName": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string", "format": "uri" }, "authorName": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "title" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bodyHtml": { "type": "string" } }, "required": [ "bodyHtml" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.preview", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Reads article data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": { "title": "Preview article", "body": [ { "type": "paragraph", "text": "Preview body." } ] }, "expected": "A response matching the published outputSchema for articles.preview." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "title": "Preview article", "body": [ { "type": "paragraph", "text": "Preview body." } ] }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "POST", "path": "/api/articles/preview", "body": { "title": "Preview article", "body": [ { "type": "paragraph", "text": "Preview body." } ] } }, "effects": "Reads article data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.preview", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/articles/preview", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.get", "title": "Get article", "description": "Get one article from the selected editorial workspace.", "method": "GET", "path": "/api/articles/{articleId}", "permission": "workspace:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.get", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Reads article data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": { "articleId": "article_example" }, "expected": "A response matching the published outputSchema for articles.get." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "articleId": "article_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/articles/article_example", "body": null }, "effects": "Reads article data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.get", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/articles/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.revisions.list", "title": "List article revisions", "description": "List the immutable revisions for an article.", "method": "GET", "path": "/api/articles/{articleId}/revisions", "permission": "workspace:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "articleId": { "type": "string" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "snapshot": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId" ], "additionalProperties": false }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "articleId", "revisionNumber", "snapshot", "createdByUserId", "createdAt" ], "additionalProperties": false } } }, "required": [ "revisions" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.revisions.list", "resource": { "kind": "article", "idPath": "$.items[].id" }, "effects": [ "Reads article data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": { "articleId": "article_example" }, "expected": "A response matching the published outputSchema for articles.revisions.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "articleId": "article_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/articles/article_example/revisions", "body": null }, "effects": "Reads article data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.revisions.list", "resource": { "kind": "article", "idPath": "$.items[].id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/articles/*/revisions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.revisions.restore", "title": "Restore article revision", "description": "Restore an immutable revision as a new unpublished article revision.", "method": "POST", "path": "/api/articles/{articleId}/revisions/{revisionNumber}/restore", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 }, "revisionNumber": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "articleId", "revisionNumber" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.revisions.restore", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Changes article state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "articleId": "article_example", "revisionNumber": 2 }, "expected": "A response matching the published outputSchema for articles.revisions.restore." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "articleId": "article_example", "revisionNumber": 2 }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/articles/article_example/revisions/2/restore", "body": { "articleId": "article_example", "revisionNumber": 2 } }, "effects": "Changes article state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.revisions.restore", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/articles/*/revisions/*/restore", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.create", "title": "Create article", "description": "Create a new draft article in the selected editorial workspace. Always yields a draft: to go live, request review, approve, then publish or schedule.", "method": "POST", "path": "/api/articles", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Article headline; renders as the page H1 and seeds the slug when slug is omitted." }, "slug": { "description": "URL path segment. Omit to derive it from the title.", "type": "string", "maxLength": 120 }, "publicationId": { "description": "Target publication id from publications.list. Omit to use the workspace default publication.", "type": "string", "minLength": 1 }, "excerpt": { "type": "string", "maxLength": 320 }, "body": { "description": "Ordered article content as typed blocks (paragraph, heading, list, image, quote, divider, code, callout). Text fields accept inline markdown: **bold**, *italic*, `code`, [label](https://…).", "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "maxItems": 12, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 48 } }, "seriesName": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string", "format": "uri" }, "authorName": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "title" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.create", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Changes article state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "title": "How we ship every week", "excerpt": "The release habits that keep our team shipping weekly without breaking production.", "body": [ { "type": "paragraph", "text": "Shipping weekly is a **habit**, not a heroic effort. This post covers the *three* practices that make it routine." }, { "type": "heading", "level": 2, "text": "Keep changes small" }, { "type": "list", "style": "unordered", "items": [ "**Small diffs:** easier to review and revert.", "**Feature flags:** decouple deploy from release — see [our guide](https://example.com/flags)." ] }, { "type": "quote", "text": "If a release is scary, do it more often.", "attribution": "Engineering handbook" }, { "type": "code", "language": "bash", "code": "git switch -c release/weekly\ngit push origin release/weekly" }, { "type": "callout", "tone": "info", "title": "Draft first", "text": "Creating an article always produces a draft. Request review, approve, then publish or schedule it." }, { "type": "divider" }, { "type": "heading", "level": 3, "text": "What we measure" }, { "type": "paragraph", "text": "Lead time, review latency, and the rollback count — tracked per `release` tag." } ], "tags": [ "engineering", "process" ] }, "expected": "A response matching the published outputSchema for articles.create." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata", "nextActionIds": [ "app_topolo_blog.articles.update", "app_topolo_blog.media.upload", "app_topolo_blog.articles.checks.get", "app_topolo_blog.articles.review.request" ] }, "documentation": { "example_input": { "title": "How we ship every week", "excerpt": "The release habits that keep our team shipping weekly without breaking production.", "body": [ { "type": "paragraph", "text": "Shipping weekly is a **habit**, not a heroic effort. This post covers the *three* practices that make it routine." }, { "type": "heading", "level": 2, "text": "Keep changes small" }, { "type": "list", "style": "unordered", "items": [ "**Small diffs:** easier to review and revert.", "**Feature flags:** decouple deploy from release — see [our guide](https://example.com/flags)." ] }, { "type": "quote", "text": "If a release is scary, do it more often.", "attribution": "Engineering handbook" }, { "type": "code", "language": "bash", "code": "git switch -c release/weekly\ngit push origin release/weekly" }, { "type": "callout", "tone": "info", "title": "Draft first", "text": "Creating an article always produces a draft. Request review, approve, then publish or schedule it." }, { "type": "divider" }, { "type": "heading", "level": 3, "text": "What we measure" }, { "type": "paragraph", "text": "Lead time, review latency, and the rollback count — tracked per `release` tag." } ], "tags": [ "engineering", "process" ] }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/articles", "body": { "title": "How we ship every week", "excerpt": "The release habits that keep our team shipping weekly without breaking production.", "body": [ { "type": "paragraph", "text": "Shipping weekly is a **habit**, not a heroic effort. This post covers the *three* practices that make it routine." }, { "type": "heading", "level": 2, "text": "Keep changes small" }, { "type": "list", "style": "unordered", "items": [ "**Small diffs:** easier to review and revert.", "**Feature flags:** decouple deploy from release — see [our guide](https://example.com/flags)." ] }, { "type": "quote", "text": "If a release is scary, do it more often.", "attribution": "Engineering handbook" }, { "type": "code", "language": "bash", "code": "git switch -c release/weekly\ngit push origin release/weekly" }, { "type": "callout", "tone": "info", "title": "Draft first", "text": "Creating an article always produces a draft. Request review, approve, then publish or schedule it." }, { "type": "divider" }, { "type": "heading", "level": 3, "text": "What we measure" }, { "type": "paragraph", "text": "Lead time, review latency, and the rollback count — tracked per `release` tag." } ], "tags": [ "engineering", "process" ] } }, "effects": "Changes article state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.create", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [ "app_topolo_blog.articles.update", "app_topolo_blog.media.upload", "app_topolo_blog.articles.checks.get", "app_topolo_blog.articles.review.request" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/articles", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.update", "title": "Update article", "description": "Update an article and append an immutable revision. Provided fields replace their previous values (body is replaced whole, not merged), and any edit resets review status to draft.", "method": "PATCH", "path": "/api/articles/{articleId}", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Article headline; renders as the page H1 and seeds the slug when slug is omitted." }, "slug": { "description": "URL path segment. Omit to derive it from the title.", "type": "string", "maxLength": 120 }, "publicationId": { "description": "Target publication id from publications.list. Omit to use the workspace default publication.", "type": "string", "minLength": 1 }, "excerpt": { "type": "string", "maxLength": 320 }, "body": { "description": "Ordered article content as typed blocks (paragraph, heading, list, image, quote, divider, code, callout). Text fields accept inline markdown: **bold**, *italic*, `code`, [label](https://…).", "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "maxItems": 12, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 48 } }, "seriesName": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string", "format": "uri" }, "authorName": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "articleId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.update", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Changes article state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "articleId": "article_example", "title": "Updated title", "body": [ { "type": "paragraph", "text": "Replaces the whole body: send the complete block array, not a fragment." } ] }, "expected": "A response matching the published outputSchema for articles.update." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata", "nextActionIds": [ "app_topolo_blog.articles.checks.get", "app_topolo_blog.articles.review.request" ] }, "documentation": { "example_input": { "articleId": "article_example", "title": "Updated title", "body": [ { "type": "paragraph", "text": "Replaces the whole body: send the complete block array, not a fragment." } ] }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/articles/article_example", "body": { "articleId": "article_example", "title": "Updated title", "body": [ { "type": "paragraph", "text": "Replaces the whole body: send the complete block array, not a fragment." } ] } }, "effects": "Changes article state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.update", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [ "app_topolo_blog.articles.checks.get", "app_topolo_blog.articles.review.request" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/articles/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.delete", "title": "Delete article", "description": "Permanently delete an article and its immutable revisions from the selected editorial workspace.", "method": "DELETE", "path": "/api/articles/{articleId}", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "articleId": { "type": "string" } }, "required": [ "deleted", "articleId" ], "additionalProperties": false }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.delete", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Changes article state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "articleId": "article_example" }, "expected": "A response matching the published outputSchema for articles.delete." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "articleId": "article_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/articles/article_example", "body": null }, "effects": "Changes article state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.delete", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/articles/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.review.request", "title": "Request article review", "description": "Submit the current article revision for editorial review.", "method": "POST", "path": "/api/articles/{articleId}/review/request", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.review.request", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Changes article state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "articleId": "article_example" }, "expected": "A response matching the published outputSchema for articles.review.request." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata", "nextActionIds": [ "app_topolo_blog.articles.review.approve", "app_topolo_blog.articles.review.changes.request" ] }, "documentation": { "example_input": { "articleId": "article_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/articles/article_example/review/request", "body": { "articleId": "article_example" } }, "effects": "Changes article state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.review.request", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [ "app_topolo_blog.articles.review.approve", "app_topolo_blog.articles.review.changes.request" ], "rollback_action_id": null }, "implementation": { "status": "declared_unserved", "route_key": "POST /api/articles/*/review/request", "evidence": "No matching served route was extracted from canonical staging source." } }, { "name": "articles.review.approve", "title": "Approve article revision", "description": "Approve the exact article revision currently under review. Approval is a prerequisite for publish and schedule, and is voided by any later edit.", "method": "POST", "path": "/api/articles/{articleId}/review/approve", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.review.approve", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Changes article state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "articleId": "article_example" }, "expected": "A response matching the published outputSchema for articles.review.approve." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata", "nextActionIds": [ "app_topolo_blog.articles.publish", "app_topolo_blog.articles.schedule" ] }, "documentation": { "example_input": { "articleId": "article_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/articles/article_example/review/approve", "body": { "articleId": "article_example" } }, "effects": "Changes article state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.review.approve", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [ "app_topolo_blog.articles.publish", "app_topolo_blog.articles.schedule" ], "rollback_action_id": null }, "implementation": { "status": "declared_unserved", "route_key": "POST /api/articles/*/review/approve", "evidence": "No matching served route was extracted from canonical staging source." } }, { "name": "articles.review.changes.request", "title": "Request article changes", "description": "Return an article under review to its author with changes requested.", "method": "POST", "path": "/api/articles/{articleId}/review/changes-requested", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.review.changes.request", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Changes article state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "articleId": "article_example" }, "expected": "A response matching the published outputSchema for articles.review.changes.request." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "articleId": "article_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/articles/article_example/review/changes-requested", "body": { "articleId": "article_example" } }, "effects": "Changes article state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.review.changes.request", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "declared_unserved", "route_key": "POST /api/articles/*/review/changes-requested", "evidence": "No matching served route was extracted from canonical staging source." } }, { "name": "articles.publish", "title": "Publish approved article", "description": "Publish the approved current revision immediately while retaining later edits as unpublished changes. Fails with article_not_approved unless the current revision has been approved via the review actions.", "method": "POST", "path": "/api/articles/{articleId}/publish", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.publish", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Changes article state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "articleId": "article_example" }, "expected": "A response matching the published outputSchema for articles.publish." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "articleId": "article_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/articles/article_example/publish", "body": { "articleId": "article_example" } }, "effects": "Changes article state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.publish", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/articles/*/publish", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.schedule", "title": "Schedule approved article", "description": "Schedule the approved current revision for future publication. Fails with article_not_approved unless the current revision has been approved via the review actions.", "method": "POST", "path": "/api/articles/{articleId}/schedule", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 }, "publishAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Future release time as an ISO 8601 UTC datetime, e.g. 2026-08-20T09:00:00.000Z." } }, "required": [ "articleId", "publishAt" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.schedule", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Changes article state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "articleId": "article_example", "publishAt": "2026-08-20T09:00:00.000Z" }, "expected": "A response matching the published outputSchema for articles.schedule." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata", "nextActionIds": [ "app_topolo_blog.articles.reschedule", "app_topolo_blog.articles.schedule.cancel" ] }, "documentation": { "example_input": { "articleId": "article_example", "publishAt": "2026-08-20T09:00:00.000Z" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/articles/article_example/schedule", "body": { "articleId": "article_example", "publishAt": "2026-08-20T09:00:00.000Z" } }, "effects": "Changes article state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.schedule", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [ "app_topolo_blog.articles.reschedule", "app_topolo_blog.articles.schedule.cancel" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/articles/*/schedule", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.reschedule", "title": "Reschedule article", "description": "Replace the release time for the already scheduled revision.", "method": "POST", "path": "/api/articles/{articleId}/reschedule", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 }, "publishAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Future release time as an ISO 8601 UTC datetime, e.g. 2026-08-20T09:00:00.000Z." } }, "required": [ "articleId", "publishAt" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.reschedule", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Changes article state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "articleId": "article_example", "publishAt": "2026-08-21T09:00:00.000Z" }, "expected": "A response matching the published outputSchema for articles.reschedule." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "articleId": "article_example", "publishAt": "2026-08-21T09:00:00.000Z" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/articles/article_example/reschedule", "body": { "articleId": "article_example", "publishAt": "2026-08-21T09:00:00.000Z" } }, "effects": "Changes article state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.reschedule", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/articles/*/reschedule", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.schedule.cancel", "title": "Cancel article schedule", "description": "Cancel the pending scheduled release without changing any currently published revision.", "method": "POST", "path": "/api/articles/{articleId}/schedule/cancel", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.schedule.cancel", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Changes article state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "articleId": "article_example" }, "expected": "A response matching the published outputSchema for articles.schedule.cancel." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "articleId": "article_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/articles/article_example/schedule/cancel", "body": { "articleId": "article_example" } }, "effects": "Changes article state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.schedule.cancel", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/articles/*/schedule/cancel", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.unpublish", "title": "Unpublish article", "description": "Remove the currently published revision from public delivery while retaining editorial history.", "method": "POST", "path": "/api/articles/{articleId}/unpublish", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.unpublish", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Changes article state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "articleId": "article_example" }, "expected": "A response matching the published outputSchema for articles.unpublish." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "articleId": "article_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/articles/article_example/unpublish", "body": { "articleId": "article_example" } }, "effects": "Changes article state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.unpublish", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/articles/*/unpublish", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.duplicate", "title": "Duplicate article", "description": "Create a new draft from an existing article without copying its publication state.", "method": "POST", "path": "/api/articles/{articleId}/duplicate", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.duplicate", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Changes article state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "articleId": "article_example" }, "expected": "A response matching the published outputSchema for articles.duplicate." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "articleId": "article_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/articles/article_example/duplicate", "body": { "articleId": "article_example" } }, "effects": "Changes article state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.duplicate", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/articles/*/duplicate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.checks.get", "title": "Check article readiness", "description": "Run SEO completeness, accessibility, and bounded broken-link checks for an article.", "method": "GET", "path": "/api/articles/{articleId}/checks", "permission": "workspace:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "checks": { "type": "object", "properties": { "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "pass", "warning", "error" ] }, "message": { "type": "string" } }, "required": [ "id", "label", "status", "message" ], "additionalProperties": false } }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "broken", "blocked" ] }, "statusCode": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "url", "status", "statusCode" ], "additionalProperties": false } }, "complete": { "type": "boolean" } }, "required": [ "checks", "links", "complete" ], "additionalProperties": false } }, "required": [ "checks" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.checks.get", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Reads article data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": { "articleId": "article_example" }, "expected": "A response matching the published outputSchema for articles.checks.get." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "articleId": "article_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/articles/article_example/checks", "body": null }, "effects": "Reads article data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.checks.get", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/articles/*/checks", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "articles.bulk", "title": "Run bulk article operation", "description": "Apply one governed editorial operation to up to 100 selected articles.", "method": "POST", "path": "/api/articles/bulk", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "operation": { "type": "string", "enum": [ "request_review", "approve", "publish", "unpublish", "delete" ] } }, "required": [ "articleIds", "operation" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "articleId": { "type": "string" }, "success": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "articleId", "success", "error" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.bulk", "resource": { "kind": "article", "idPath": "$.id" }, "effects": [ "Changes article state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "articleIds": [ "article_example" ], "operation": "request_review" }, "expected": "A response matching the published outputSchema for articles.bulk." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "articleIds": [ "article_example" ], "operation": "request_review" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/articles/bulk", "body": { "articleIds": [ "article_example" ], "operation": "request_review" } }, "effects": "Changes article state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=articles.bulk", "resource": { "kind": "article", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/articles/bulk", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "templates.list", "title": "List article templates", "description": "List reusable article templates in the selected editorial workspace.", "method": "GET", "path": "/api/templates", "permission": "workspace:read", "authorizationMode": "static", "readOnly": true, "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": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "titlePattern": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "titlePattern", "excerpt", "body", "tags", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "templates" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=templates.list", "resource": { "kind": "article_template", "idPath": "$.items[].id" }, "effects": [ "Reads article template data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for templates.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/templates", "body": null }, "effects": "Reads article template data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=templates.list", "resource": { "kind": "article_template", "idPath": "$.items[].id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/templates", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "templates.create", "title": "Create article template", "description": "Create a reusable article structure for the selected editorial workspace.", "method": "POST", "path": "/api/templates", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 320 }, "titlePattern": { "type": "string", "maxLength": 160 }, "excerpt": { "type": "string", "maxLength": 320 }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "maxItems": 12, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 48 } } }, "required": [ "name" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "template": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "titlePattern": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "titlePattern", "excerpt", "body", "tags", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "template" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=templates.create", "resource": { "kind": "article_template", "idPath": "$.id" }, "effects": [ "Changes article template state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "name": "Product announcement", "body": [ { "type": "paragraph", "text": "Opening." } ] }, "expected": "A response matching the published outputSchema for templates.create." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "name": "Product announcement", "body": [ { "type": "paragraph", "text": "Opening." } ] }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/templates", "body": { "name": "Product announcement", "body": [ { "type": "paragraph", "text": "Opening." } ] } }, "effects": "Changes article template state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=templates.create", "resource": { "kind": "article_template", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/templates", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "templates.delete", "title": "Delete article template", "description": "Delete a reusable article template.", "method": "DELETE", "path": "/api/templates/{templateId}", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "templateId": { "type": "string", "minLength": 1 } }, "required": [ "templateId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "templateId": { "type": "string" } }, "required": [ "deleted", "templateId" ], "additionalProperties": false }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=templates.delete", "resource": { "kind": "article_template", "idPath": "$.id" }, "effects": [ "Changes article template state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "templateId": "template_example" }, "expected": "A response matching the published outputSchema for templates.delete." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "templateId": "template_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/templates/template_example", "body": null }, "effects": "Changes article template state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=templates.delete", "resource": { "kind": "article_template", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "declared_unserved", "route_key": "DELETE /api/templates/*", "evidence": "No matching served route was extracted from canonical staging source." } }, { "name": "saved_searches.list", "title": "List saved article searches", "description": "List saved article search and sorting configurations.", "method": "GET", "path": "/api/saved-searches", "permission": "workspace:read", "authorizationMode": "static", "readOnly": true, "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": { "searches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "query": { "type": "string" }, "status": { "type": "string", "enum": [ "all", "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "all", "draft", "in_review", "changes_requested", "approved" ] }, "sort": { "type": "string", "enum": [ "updatedAt", "title", "publishedAt" ] }, "order": { "type": "string", "enum": [ "asc", "desc" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "query", "status", "reviewStatus", "sort", "order", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "searches" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=saved_searches.list", "resource": { "kind": "saved_search", "idPath": "$.items[].id" }, "effects": [ "Reads saved search data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for saved_searches.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/saved-searches", "body": null }, "effects": "Reads saved search data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=saved_searches.list", "resource": { "kind": "saved_search", "idPath": "$.items[].id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/saved-searches", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "saved_searches.create", "title": "Create saved article search", "description": "Save an article query, workflow filter, and sort order.", "method": "POST", "path": "/api/saved-searches", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "query": { "type": "string", "maxLength": 160 }, "status": { "type": "string", "enum": [ "all", "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "all", "draft", "in_review", "changes_requested", "approved" ] }, "sort": { "type": "string", "enum": [ "updatedAt", "title", "publishedAt" ] }, "order": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "name" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "query": { "type": "string" }, "status": { "type": "string", "enum": [ "all", "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "all", "draft", "in_review", "changes_requested", "approved" ] }, "sort": { "type": "string", "enum": [ "updatedAt", "title", "publishedAt" ] }, "order": { "type": "string", "enum": [ "asc", "desc" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "query", "status", "reviewStatus", "sort", "order", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "search" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=saved_searches.create", "resource": { "kind": "saved_search", "idPath": "$.id" }, "effects": [ "Changes saved search state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "name": "Needs approval", "reviewStatus": "in_review" }, "expected": "A response matching the published outputSchema for saved_searches.create." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "name": "Needs approval", "reviewStatus": "in_review" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/saved-searches", "body": { "name": "Needs approval", "reviewStatus": "in_review" } }, "effects": "Changes saved search state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=saved_searches.create", "resource": { "kind": "saved_search", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/saved-searches", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "saved_searches.delete", "title": "Delete saved article search", "description": "Delete a saved article search configuration.", "method": "DELETE", "path": "/api/saved-searches/{searchId}", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "searchId": { "type": "string", "minLength": 1 } }, "required": [ "searchId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "searchId": { "type": "string" } }, "required": [ "deleted", "searchId" ], "additionalProperties": false }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=saved_searches.delete", "resource": { "kind": "saved_search", "idPath": "$.id" }, "effects": [ "Changes saved search state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "searchId": "search_example" }, "expected": "A response matching the published outputSchema for saved_searches.delete." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "searchId": "search_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/saved-searches/search_example", "body": null }, "effects": "Changes saved search state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=saved_searches.delete", "resource": { "kind": "saved_search", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "declared_unserved", "route_key": "DELETE /api/saved-searches/*", "evidence": "No matching served route was extracted from canonical staging source." } }, { "name": "publications.list", "title": "List publications", "description": "List configured publishing destinations for the selected workspace.", "method": "GET", "path": "/api/publications", "permission": "workspace:read", "authorizationMode": "static", "readOnly": true, "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": { "publications": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "baseUrl": { "type": "string" }, "description": { "type": "string" }, "defaultSeoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultSeoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "articleCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "name", "slug", "baseUrl", "description", "defaultSeoTitle", "defaultSeoDescription", "isDefault", "articleCount", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "publications" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=publications.list", "resource": { "kind": "publication", "idPath": "$.items[].id" }, "effects": [ "Reads publication data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for publications.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/publications", "body": null }, "effects": "Reads publication data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=publications.list", "resource": { "kind": "publication", "idPath": "$.items[].id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/publications", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "publications.create", "title": "Create publication", "description": "Create a named publishing destination with a canonical base URL.", "method": "POST", "path": "/api/publications", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "baseUrl": { "type": "string", "format": "uri" }, "description": { "type": "string", "maxLength": 320 }, "defaultSeoTitle": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "defaultSeoDescription": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "slug": { "type": "string", "maxLength": 63 } }, "required": [ "name", "baseUrl" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publication": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "baseUrl": { "type": "string" }, "description": { "type": "string" }, "defaultSeoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultSeoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "articleCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "name", "slug", "baseUrl", "description", "defaultSeoTitle", "defaultSeoDescription", "isDefault", "articleCount", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "publication" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=publications.create", "resource": { "kind": "publication", "idPath": "$.id" }, "effects": [ "Changes publication state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "name": "Company blog", "baseUrl": "https://example.com/blog" }, "expected": "A response matching the published outputSchema for publications.create." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "name": "Company blog", "baseUrl": "https://example.com/blog" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/publications", "body": { "name": "Company blog", "baseUrl": "https://example.com/blog" } }, "effects": "Changes publication state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=publications.create", "resource": { "kind": "publication", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/publications", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "publications.update", "title": "Update publication", "description": "Update a publication name, destination, description, and SEO defaults.", "method": "PATCH", "path": "/api/publications/{publicationId}", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publicationId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "baseUrl": { "type": "string", "format": "uri" }, "description": { "type": "string", "maxLength": 320 }, "defaultSeoTitle": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "defaultSeoDescription": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "publicationId", "name", "baseUrl" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publication": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "baseUrl": { "type": "string" }, "description": { "type": "string" }, "defaultSeoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultSeoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "articleCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "name", "slug", "baseUrl", "description", "defaultSeoTitle", "defaultSeoDescription", "isDefault", "articleCount", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "publication" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=publications.update", "resource": { "kind": "publication", "idPath": "$.id" }, "effects": [ "Changes publication state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "publicationId": "publication_example", "name": "Company blog", "baseUrl": "https://example.com/blog" }, "expected": "A response matching the published outputSchema for publications.update." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "publicationId": "publication_example", "name": "Company blog", "baseUrl": "https://example.com/blog" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/publications/publication_example", "body": { "publicationId": "publication_example", "name": "Company blog", "baseUrl": "https://example.com/blog" } }, "effects": "Changes publication state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=publications.update", "resource": { "kind": "publication", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/publications/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "publications.default.set", "title": "Set default publication", "description": "Choose the publication used automatically for new articles.", "method": "POST", "path": "/api/publications/{publicationId}/default", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publicationId": { "type": "string", "minLength": 1 } }, "required": [ "publicationId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publication": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "baseUrl": { "type": "string" }, "description": { "type": "string" }, "defaultSeoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultSeoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "articleCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "name", "slug", "baseUrl", "description", "defaultSeoTitle", "defaultSeoDescription", "isDefault", "articleCount", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "publication" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=publications.default.set", "resource": { "kind": "publication", "idPath": "$.id" }, "effects": [ "Changes publication state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "publicationId": "publication_example" }, "expected": "A response matching the published outputSchema for publications.default.set." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "publicationId": "publication_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/publications/publication_example/default", "body": { "publicationId": "publication_example" } }, "effects": "Changes publication state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=publications.default.set", "resource": { "kind": "publication", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/publications/*/default", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "publications.delete", "title": "Delete publication", "description": "Delete an unused non-default publication.", "method": "DELETE", "path": "/api/publications/{publicationId}", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publicationId": { "type": "string", "minLength": 1 } }, "required": [ "publicationId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "publicationId": { "type": "string" } }, "required": [ "deleted", "publicationId" ], "additionalProperties": false }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=publications.delete", "resource": { "kind": "publication", "idPath": "$.id" }, "effects": [ "Changes publication state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "publicationId": "publication_example" }, "expected": "A response matching the published outputSchema for publications.delete." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "publicationId": "publication_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/publications/publication_example", "body": null }, "effects": "Changes publication state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=publications.delete", "resource": { "kind": "publication", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/publications/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.list", "title": "List media", "description": "List reusable Blog media assets in the selected workspace.", "method": "GET", "path": "/api/media", "permission": "workspace:read", "authorizationMode": "static", "readOnly": true, "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": { "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "byteSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "altText": { "type": "string" }, "url": { "type": "string" }, "usageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "fileName", "contentType", "byteSize", "altText", "url", "usageCount", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "assets" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=media.list", "resource": { "kind": "media_asset", "idPath": "$.items[].id" }, "effects": [ "Reads media asset data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for media.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/media", "body": null }, "effects": "Reads media asset data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=media.list", "resource": { "kind": "media_asset", "idPath": "$.items[].id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/media", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.upload", "title": "Upload media", "description": "Upload a reusable image to the Blog media library. The response asset provides the assetId and url an article image block requires.", "method": "POST", "path": "/api/media", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentBase64": { "type": "string", "minLength": 1 }, "contentType": { "type": "string", "enum": [ "image/gif", "image/jpeg", "image/png", "image/webp" ] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "altText": { "type": "string", "maxLength": 320 } }, "required": [ "contentBase64", "contentType", "fileName" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "byteSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "altText": { "type": "string" }, "url": { "type": "string" }, "usageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "fileName", "contentType", "byteSize", "altText", "url", "usageCount", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "asset" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=media.upload", "resource": { "kind": "media_asset", "idPath": "$.id" }, "effects": [ "Changes media asset state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "contentBase64": "iVBORw0KGgo=", "contentType": "image/png", "fileName": "example.png" }, "expected": "A response matching the published outputSchema for media.upload." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata", "nextActionIds": [ "app_topolo_blog.articles.create", "app_topolo_blog.articles.update" ], "upload": { "profile": "inline-base64", "contentField": "contentBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 10485760, "acceptedContentTypes": [ "image/gif", "image/jpeg", "image/png", "image/webp" ] } }, "documentation": { "example_input": { "contentBase64": "iVBORw0KGgo=", "contentType": "image/png", "fileName": "example.png" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/media", "body": { "contentBase64": "iVBORw0KGgo=", "contentType": "image/png", "fileName": "example.png" } }, "effects": "Changes media asset state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=media.upload", "resource": { "kind": "media_asset", "idPath": "$.id" }, "next_action_ids": [ "app_topolo_blog.articles.create", "app_topolo_blog.articles.update" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/media", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.update", "title": "Update media", "description": "Update alternative text for a Blog media asset.", "method": "PATCH", "path": "/api/media/{assetId}", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "assetId": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "maxLength": 320 } }, "required": [ "assetId", "altText" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "byteSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "altText": { "type": "string" }, "url": { "type": "string" }, "usageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "fileName", "contentType", "byteSize", "altText", "url", "usageCount", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "asset" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=media.update", "resource": { "kind": "media_asset", "idPath": "$.id" }, "effects": [ "Changes media asset state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "assetId": "media_example", "altText": "A useful description" }, "expected": "A response matching the published outputSchema for media.update." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "assetId": "media_example", "altText": "A useful description" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/media/media_example", "body": { "assetId": "media_example", "altText": "A useful description" } }, "effects": "Changes media asset state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=media.update", "resource": { "kind": "media_asset", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/media/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.delete", "title": "Delete media", "description": "Permanently delete a Blog media asset.", "method": "DELETE", "path": "/api/media/{assetId}", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "assetId": { "type": "string", "minLength": 1 } }, "required": [ "assetId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "assetId": { "type": "string" } }, "required": [ "deleted", "assetId" ], "additionalProperties": false }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=media.delete", "resource": { "kind": "media_asset", "idPath": "$.id" }, "effects": [ "Changes media asset state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "assetId": "media_example" }, "expected": "A response matching the published outputSchema for media.delete." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "assetId": "media_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/media/media_example", "body": null }, "effects": "Changes media asset state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=media.delete", "resource": { "kind": "media_asset", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/media/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "settings.get", "title": "Get editorial settings", "description": "Get workspace-level editorial and SEO defaults.", "method": "GET", "path": "/api/settings", "permission": "workspace:read", "authorizationMode": "static", "readOnly": true, "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": { "settings": { "type": "object", "properties": { "editorialName": { "type": "string" }, "defaultAuthorName": { "type": "string" }, "defaultSeoTitle": { "type": "string" }, "defaultSeoDescription": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "editorialName", "defaultAuthorName", "defaultSeoTitle", "defaultSeoDescription", "updatedAt" ], "additionalProperties": false } }, "required": [ "settings" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=settings.get", "resource": { "kind": "workspace", "idPath": "$.id" }, "effects": [ "Reads workspace data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for settings.get." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/settings", "body": null }, "effects": "Reads workspace data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=settings.get", "resource": { "kind": "workspace", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "settings.update", "title": "Update editorial settings", "description": "Update workspace-level editorial and SEO defaults.", "method": "PUT", "path": "/api/settings", "permission": "workspace:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "editorialName": { "type": "string", "maxLength": 100 }, "defaultAuthorName": { "type": "string", "maxLength": 100 }, "defaultSeoTitle": { "type": "string", "maxLength": 160 }, "defaultSeoDescription": { "type": "string", "maxLength": 320 } }, "required": [ "editorialName", "defaultAuthorName", "defaultSeoTitle", "defaultSeoDescription" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "settings": { "type": "object", "properties": { "editorialName": { "type": "string" }, "defaultAuthorName": { "type": "string" }, "defaultSeoTitle": { "type": "string" }, "defaultSeoDescription": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "editorialName", "defaultAuthorName", "defaultSeoTitle", "defaultSeoDescription", "updatedAt" ], "additionalProperties": false } }, "required": [ "settings" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=settings.update", "resource": { "kind": "workspace", "idPath": "$.id" }, "effects": [ "Changes workspace state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "editorialName": "Editorial team", "defaultAuthorName": "Topolo", "defaultSeoTitle": "Company blog", "defaultSeoDescription": "News and perspectives from the team." }, "expected": "A response matching the published outputSchema for settings.update." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "editorialName": "Editorial team", "defaultAuthorName": "Topolo", "defaultSeoTitle": "Company blog", "defaultSeoDescription": "News and perspectives from the team." }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/settings", "body": { "editorialName": "Editorial team", "defaultAuthorName": "Topolo", "defaultSeoTitle": "Company blog", "defaultSeoDescription": "News and perspectives from the team." } }, "effects": "Changes workspace state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=settings.update", "resource": { "kind": "workspace", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.export", "title": "Export organization data", "description": "Export all TopoloBlog articles and immutable revisions for the authenticated organization.", "method": "GET", "path": "/api/organizations/{organizationId}/data", "permission": "privacy:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "organizationId": { "type": "string" }, "credentialsIncluded": { "type": "boolean", "const": false }, "exportedAt": { "type": "string" }, "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id" ], "additionalProperties": {} } }, "revisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "article_id": { "type": "string" } }, "required": [ "id", "article_id" ], "additionalProperties": {} } } }, "required": [ "organizationId", "credentialsIncluded", "exportedAt", "articles", "revisions" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=organizations.data.export", "resource": { "kind": "organization", "idPath": "$.id" }, "effects": [ "Reads organization data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission privacy:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": { "organizationId": "organization_example" }, "expected": "A response matching the published outputSchema for organizations.data.export." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "organizationId": "organization_example" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/organization_example/data", "body": null }, "effects": "Reads organization data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission privacy:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=organizations.data.export", "resource": { "kind": "organization", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.erase", "title": "Erase organization data", "description": "Erase all TopoloBlog articles and revisions for the authenticated organization after literal ERASE confirmation.", "method": "DELETE", "path": "/api/organizations/{organizationId}/data", "permission": "privacy:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "organizationId", "confirmation" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "organizationId": { "type": "string" }, "erased": { "type": "boolean", "const": true } }, "required": [ "organizationId", "erased" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=organizations.data.erase", "resource": { "kind": "organization", "idPath": "$.id" }, "effects": [ "Changes organization state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission privacy:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "organizationId": "organization_example", "confirmation": "ERASE" }, "expected": "A response matching the published outputSchema for organizations.data.erase." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "derived-action-metadata" }, "documentation": { "example_input": { "organizationId": "organization_example", "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-blog --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/organization_example/data", "body": null }, "effects": "Changes organization state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission privacy:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-blog&action=organizations.data.erase", "resource": { "kind": "organization", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 44, "matched_actions": 37, "declared_unserved_actions": [ "DELETE /api/saved-searches/*", "DELETE /api/templates/*", "POST /api/articles/*/review/approve", "POST /api/articles/*/review/changes-requested", "POST /api/articles/*/review/request" ], "coverage_excluded_actions": [], "uncatalogued_routes": [ { "key": "DELETE /api/saved-searches", "method": "DELETE", "path": "/api/saved-searches", "source": "apps/api/src/editorial-routes.ts", "target": "api" }, { "key": "DELETE /api/templates", "method": "DELETE", "path": "/api/templates", "source": "apps/api/src/editorial-routes.ts", "target": "api" }, { "key": "GET /api/public/publications", "method": "GET", "path": "/api/public/publications", "source": "apps/api/src/article-routes.ts", "target": "api" }, { "key": "GET /api/public/publications/*/*", "method": "GET", "path": "/api/public/publications/{segment1}/{segment2}", "source": "apps/api/src/article-routes.ts", "target": "api" }, { "key": "POST /api/articles/*/review", "method": "POST", "path": "/api/articles/{segment1}/review", "source": "apps/api/src/article-routes.ts", "target": "api" } ], "ignored_routes": 2, "configured_exclusions": 3, "configuration_findings": [ "GET /api/public/media/*: exclusion matches no served route", "GET /api/public/publications/*/articles: exclusion matches no served route", "GET /api/public/publications/*/articles/*: exclusion matches no served route" ], "notes": [] }, "runtime_contract_audit": { "status": "verified", "actions": 42, "contracts": 42, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/worker.ts" ], "authorization_sources": [ "apps/api/src/worker.ts" ], "findings": [] } } ], "mobile_contracts": [], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "ALL", "path": "*", "source_path": "apps/TopoloBlog/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/health", "source_path": "apps/TopoloBlog/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/app-identity", "source_path": "apps/TopoloBlog/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/widget", "source_path": "apps/TopoloBlog/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/bootstrap", "source_path": "apps/TopoloBlog/apps/api/src/worker.ts" } ], "ui_routes": [ { "path": "/getting-started", "source_path": "apps/TopoloBlog/apps/web/src/App.tsx" }, { "path": "/articles", "source_path": "apps/TopoloBlog/apps/web/src/app-routes.tsx" }, { "path": "/calendar", "source_path": "apps/TopoloBlog/apps/web/src/app-routes.tsx" }, { "path": "/media", "source_path": "apps/TopoloBlog/apps/web/src/app-routes.tsx" }, { "path": "/templates", "source_path": "apps/TopoloBlog/apps/web/src/app-routes.tsx" }, { "path": "/publications", "source_path": "apps/TopoloBlog/apps/web/src/app-routes.tsx" }, { "path": "/analytics", "source_path": "apps/TopoloBlog/apps/web/src/app-routes.tsx" }, { "path": "/settings", "source_path": "apps/TopoloBlog/apps/web/src/app-routes.tsx" }, { "path": "/settings/:section", "source_path": "apps/TopoloBlog/apps/web/src/app-routes.tsx" }, { "path": "/articles/:articleId", "source_path": "apps/TopoloBlog/apps/web/src/app-routes.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloBlog/apps/web/src/app-routes.tsx" }, { "path": "/blog/identity-is-operating-infrastructure", "source_path": "apps/TopoloBlog/apps/web/src/routes/AnalyticsRoute.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "internal/apps/blog", "applications/blog" ], "present_paths": [ "internal/apps/blog", "applications/blog" ], "missing_paths": [], "human_reference": "/systems/topolo-blog", "machine_reference": "/machine/systems/topolo-blog.json", "action_examples": 42, "action_schemas": 42 }, "source_findings": [ { "type": "declared_unserved_actions", "source_path": "apps/TopoloBlog/topolo.app.json", "detail": [ "DELETE /api/saved-searches/*", "DELETE /api/templates/*", "POST /api/articles/*/review/approve", "POST /api/articles/*/review/changes-requested", "POST /api/articles/*/review/request" ] }, { "type": "uncatalogued_routes", "source_path": "apps/TopoloBlog/topolo.app.json", "detail": [ { "key": "DELETE /api/saved-searches", "method": "DELETE", "path": "/api/saved-searches", "source": "apps/api/src/editorial-routes.ts", "target": "api" }, { "key": "DELETE /api/templates", "method": "DELETE", "path": "/api/templates", "source": "apps/api/src/editorial-routes.ts", "target": "api" }, { "key": "GET /api/public/publications", "method": "GET", "path": "/api/public/publications", "source": "apps/api/src/article-routes.ts", "target": "api" }, { "key": "GET /api/public/publications/*/*", "method": "GET", "path": "/api/public/publications/{segment1}/{segment2}", "source": "apps/api/src/article-routes.ts", "target": "api" }, { "key": "POST /api/articles/*/review", "method": "POST", "path": "/api/articles/{segment1}/review", "source": "apps/api/src/article-routes.ts", "target": "api" } ] }, { "type": "action_coverage_configuration", "source_path": "apps/TopoloBlog/topolo.app.json", "detail": [ "GET /api/public/media/*: exclusion matches no served route", "GET /api/public/publications/*/articles: exclusion matches no served route", "GET /api/public/publications/*/articles/*: exclusion matches no served route" ] } ] }, "topolo-brand": { "id": "topolo-brand", "name": "Topolo Brand", "slug": "topolo-brand", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloBrand" ], "source_revisions": [ { "source_path": "apps/TopoloBrand", "repository": "apps/TopoloBrand", "revision": "05fc4a7e6712bb2cfabb4adee7fd95ba5935c992", "ref": "origin/staging" } ], "source_counts": { "source_files": 64, "test_files": 48, "test_cases": 0, "migration_files": 10, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 29, "mobile_contracts": 0, "notifications": 6, "package_manifests": 1, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloBrand/topolo.app.json", "service_slug": "topolo-brand", "name": "topolo-brand", "app_id": "app_topolo_brand", "compatibility_date": "2026-05-05", "primary_target": null, "environments": [ "development", "production", "staging" ], "targets": [ { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/worker.ts", "worker_name": "topolo-brand-api", "subdomain": null, "healthcheck_path": "/api/health", "variable_names": [ "AUTH_BASE_URL", "BRAND_APP_URL", "NEXUS_GATEWAY_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "BRAND_CONTROL_DB", "target": null }, { "kind": "d1", "binding": "BRAND_CONTENT_DB", "target": null }, { "kind": "d1", "binding": "BRAND_ASSETS_DB", "target": null }, { "kind": "d1", "binding": "BRAND_AUDIT_DB", "target": null }, { "kind": "r2", "binding": "BRAND_OBJECTS_BUCKET", "target": null } ] }, { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-brand", "subdomain": "brand", "healthcheck_path": "/api/health", "variable_names": [ "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null } ] } ], "notifications": [ "brand.asset.processing_failed", "brand.binding.changed", "brand.kit.deleted", "brand.kit.retired", "brand.version.published", "brand.version.review_requested" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_brand", "events": [ { "type": "brand.asset.processing_failed", "version": 1, "description": "A durable Brand asset upload attempt failed after registration.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "action" }, "priority": { "const": "high" }, "severity": { "const": "critical" }, "category": { "const": "brand" }, "object_type": { "const": "brand_asset" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Brand asset upload failed", "body": "Primary logo could not be stored. Try the upload again.", "surface": "action", "priority": "high", "severity": "critical", "category": "brand", "object_type": "brand_asset", "object_id": "brand_asset_123", "cta_url": "https://brand.stg.topolo.us/brand-kits/brand_123", "cta_label": "Open brand kit", "occurred_at": "2026-07-19T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^brand:brand\\.asset\\.processing_failed:brand_audit_" } }, { "type": "brand.binding.changed", "version": 1, "description": "A durable Brand consumer-resource binding was created, changed, or removed.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "info" }, "category": { "const": "brand" }, "object_type": { "const": "brand_binding" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Brand binding changed", "body": "A resource is now using a different brand kit.", "surface": "notification", "priority": "normal", "severity": "info", "category": "brand", "object_type": "brand_binding", "object_id": "brand_binding_123", "cta_url": "https://brand.stg.topolo.us/bindings", "cta_label": "View bindings", "occurred_at": "2026-07-19T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^brand:brand\\.binding\\.changed:brand_audit_" } }, { "type": "brand.kit.deleted", "version": 1, "description": "A Brand kit was permanently deleted, with its drafts, governed asset bytes and audit trail.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "high" }, "severity": { "const": "warning" }, "category": { "const": "brand" }, "object_type": { "const": "brand_kit" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Brand kit deleted", "body": "Topolo was permanently deleted. This cannot be undone.", "surface": "notification", "priority": "high", "severity": "warning", "category": "brand", "object_type": "brand_kit", "object_id": "brand_123", "cta_url": "https://brand.stg.topolo.us/brand-kits", "cta_label": "View Brand Kits", "occurred_at": "2026-08-01T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^brand:brand\\.kit\\.deleted:brand_audit_" } }, { "type": "brand.kit.retired", "version": 1, "description": "A durable active Brand kit was retired.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "warning" }, "category": { "const": "brand" }, "object_type": { "const": "brand_kit" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Brand kit retired", "body": "Topolo is no longer available to connected products.", "surface": "notification", "priority": "normal", "severity": "warning", "category": "brand", "object_type": "brand_kit", "object_id": "brand_123", "cta_url": "https://brand.stg.topolo.us/brand-kits/brand_123", "cta_label": "Open brand kit", "occurred_at": "2026-07-19T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^brand:brand\\.kit\\.retired:brand_audit_" } }, { "type": "brand.version.published", "version": 1, "description": "A durable Brand kit version became the published version.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "success" }, "category": { "const": "brand" }, "object_type": { "const": "brand_version" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Brand version published", "body": "The new brand version is now available to connected products.", "surface": "notification", "priority": "normal", "severity": "success", "category": "brand", "object_type": "brand_version", "object_id": "brand_version_123", "cta_url": "https://brand.stg.topolo.us/brand-kits/brand_123", "cta_label": "View published version", "occurred_at": "2026-07-19T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^brand:brand\\.version\\.published:brand_audit_" } }, { "type": "brand.version.review_requested", "version": 1, "description": "A durable Brand version review request was assigned to an organization member.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "action" }, "priority": { "const": "high" }, "severity": { "const": "info" }, "category": { "const": "brand" }, "object_type": { "const": "brand_version" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Brand review requested", "body": "A teammate requested your review of a brand version.", "surface": "action", "priority": "high", "severity": "info", "category": "brand", "object_type": "brand_version", "object_id": "brand_version_123", "cta_url": "https://brand.stg.topolo.us/brand-kits/brand_123", "cta_label": "Review version", "occurred_at": "2026-07-19T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^brand:brand\\.version\\.review_requested:brand_audit_" } } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary.", "method": "GET", "path": "/api/widget", "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-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 workspace bootstrap", "description": "Get the signed workspace bootstrap.", "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-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "workspaces.delete", "title": "Delete workspace", "description": "Delete an empty, non-default Brand workspace.", "method": "DELETE", "path": "/api/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 } }, "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-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.export", "title": "Export workspace privacy data", "description": "Export all Brand records and authenticated asset download paths owned by the selected workspace.", "method": "GET", "path": "/api/privacy/export", "permission": "brand: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-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/privacy/export", "body": null }, "effects": "Reads state through GET /api/privacy/export without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/privacy/export", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.delete", "title": "Erase workspace privacy data", "description": "Erase all Brand records and asset bytes owned by the selected workspace.", "method": "DELETE", "path": "/api/privacy", "permission": "workspace:delete", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/privacy", "body": null }, "effects": "May change state through DELETE /api/privacy. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/privacy", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "retention.run", "title": "Run Brand retention", "description": "Pseudonymize expired actor identity and purge expired archived asset bytes.", "method": "POST", "path": "/api/privacy/retention", "permission": "brand:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/privacy/retention", "body": {} }, "effects": "May change state through POST /api/privacy/retention. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/privacy/retention", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kits.list", "title": "List brand kits", "description": "List canonical brand kits for the organization.", "method": "GET", "path": "/api/brand-kits", "permission": "brand: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-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand-kits", "body": null }, "effects": "Reads state through GET /api/brand-kits without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand-kits", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kits.get", "title": "Get brand kit", "description": "Get one canonical brand kit.", "method": "GET", "path": "/api/brand-kits/{id}", "permission": "brand:read", "authorizationMode": "static", "readOnly": true, "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", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand-kits/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/brand-kits/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand-kits/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kits.create", "title": "Create brand kit", "description": "Create a canonical brand kit.", "method": "POST", "path": "/api/brand-kits", "permission": "brand:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "name", "slug" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "name": "example", "slug": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brand-kits", "body": { "name": "example", "slug": "example" } }, "effects": "May change state through POST /api/brand-kits. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brand-kits", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kits.update", "title": "Update brand kit", "description": "Update brand kit metadata.", "method": "PATCH", "path": "/api/brand-kits/{id}", "permission": "brand:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/brand-kits/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PATCH /api/brand-kits/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/brand-kits/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kits.delete", "title": "Delete brand kit", "description": "Permanently delete a Brand kit that was never published and has no connections, including its governed asset bytes. Refused with 409 otherwise — retire instead.", "method": "DELETE", "path": "/api/brand-kits/{id}", "permission": "brand:delete", "authorizationMode": "static", "readOnly": false, "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", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/brand-kits/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/brand-kits/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/brand-kits/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kits.retire", "title": "Retire brand kit", "description": "Retire a brand kit and stop new resolution.", "method": "POST", "path": "/api/brand-kits/{id}/retire", "permission": "brand:write", "authorizationMode": "static", "readOnly": false, "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", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brand-kits/00000000-0000-4000-8000-000000000000/retire", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/brand-kits/{id}/retire. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brand-kits/*/retire", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kit_versions.list", "title": "List brand versions", "description": "List immutable and draft versions for a brand kit.", "method": "GET", "path": "/api/brand-kits/{brandKitId}/versions", "permission": "brand:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "brandKitId": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand-kits/example/versions", "body": null }, "effects": "Reads state through GET /api/brand-kits/{brandKitId}/versions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand-kits/*/versions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kit_versions.get", "title": "Get brand version", "description": "Get an exact brand kit version.", "method": "GET", "path": "/api/brand-kits/{brandKitId}/versions/{versionId}", "permission": "brand:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId", "versionId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "brandKitId": "example", "versionId": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand-kits/example/versions/example", "body": null }, "effects": "Reads state through GET /api/brand-kits/{brandKitId}/versions/{versionId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand-kits/*/versions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kit_versions.create", "title": "Create brand version", "description": "Create a draft versioned brand snapshot.", "method": "POST", "path": "/api/brand-kits/{brandKitId}/versions", "permission": "brand:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "snapshot": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "changeNote": { "type": "string" } }, "required": [ "brandKitId", "snapshot" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "brandKitId": "example", "snapshot": {} }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brand-kits/example/versions", "body": { "brandKitId": "example", "snapshot": {} } }, "effects": "May change state through POST /api/brand-kits/{brandKitId}/versions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brand-kits/*/versions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kit_versions.update", "title": "Update draft brand version", "description": "Update a draft version before publishing.", "method": "PATCH", "path": "/api/brand-kits/{brandKitId}/versions/{versionId}", "permission": "brand:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 }, "snapshot": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "changeNote": { "type": "string" } }, "required": [ "brandKitId", "versionId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "brandKitId": "example", "versionId": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/brand-kits/example/versions/example", "body": { "brandKitId": "example", "versionId": "example" } }, "effects": "May change state through PATCH /api/brand-kits/{brandKitId}/versions/{versionId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/brand-kits/*/versions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kit_versions.publish", "title": "Publish brand version", "description": "Publish an immutable brand snapshot for consumers. Refused with 422 and the failing issues when the snapshot breaks its own governance rules — an unresolved logo reference, or a palette below the brand’s declared minimum contrast.", "method": "POST", "path": "/api/brand-kits/{brandKitId}/versions/{versionId}/publish", "permission": "brand:publish", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId", "versionId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "brandKitId": "example", "versionId": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brand-kits/example/versions/example/publish", "body": { "brandKitId": "example", "versionId": "example" } }, "effects": "May change state through POST /api/brand-kits/{brandKitId}/versions/{versionId}/publish. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brand-kits/*/versions/*/publish", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kit_versions.discard", "title": "Discard brand draft", "description": "Delete a working draft that was started and not wanted. Published and retired versions are immutable and cannot be discarded.", "method": "DELETE", "path": "/api/brand-kits/{brandKitId}/versions/{versionId}", "permission": "brand:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId", "versionId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "brandKitId": "example", "versionId": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/brand-kits/example/versions/example", "body": null }, "effects": "May change state through DELETE /api/brand-kits/{brandKitId}/versions/{versionId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/brand-kits/*/versions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kit_versions.restore", "title": "Restore brand version", "description": "Copy an earlier version’s snapshot into the working draft. The earlier version is never revived — published versions are immutable and consumers recorded their ids — so this produces an ordinary draft to review and publish.", "method": "POST", "path": "/api/brand-kits/{brandKitId}/versions/{versionId}/restore", "permission": "brand:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId", "versionId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "brandKitId": "example", "versionId": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brand-kits/example/versions/example/restore", "body": { "brandKitId": "example", "versionId": "example" } }, "effects": "May change state through POST /api/brand-kits/{brandKitId}/versions/{versionId}/restore. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brand-kits/*/versions/*/restore", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kit_versions.request_review", "title": "Request brand version review", "description": "Assign a draft brand version to an organization member for review.", "method": "POST", "path": "/api/brand-kits/{brandKitId}/versions/{versionId}/review", "permission": "brand:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 }, "reviewerUserId": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId", "versionId", "reviewerUserId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "brandKitId": "example", "versionId": "example", "reviewerUserId": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brand-kits/example/versions/example/review", "body": { "brandKitId": "example", "versionId": "example", "reviewerUserId": "example" } }, "effects": "May change state through POST /api/brand-kits/{brandKitId}/versions/{versionId}/review. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brand-kits/*/versions/*/review", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_bindings.list", "title": "List brand bindings", "description": "List consumer resources bound to brand kits.", "method": "GET", "path": "/api/brand-bindings", "permission": "brand: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-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand-bindings", "body": null }, "effects": "Reads state through GET /api/brand-bindings without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand-bindings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_bindings.upsert", "title": "Bind consumer resource", "description": "Bind an app resource to a canonical brand kit.", "method": "PUT", "path": "/api/brand-bindings", "permission": "brand:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "consumerAppId": { "type": "string", "minLength": 1 }, "externalResourceType": { "type": "string", "minLength": 1 }, "externalResourceId": { "type": "string", "minLength": 1 }, "brandKitId": { "type": "string", "minLength": 1 } }, "required": [ "consumerAppId", "externalResourceType", "externalResourceId", "brandKitId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "consumerAppId": "example", "externalResourceType": "example", "externalResourceId": "example", "brandKitId": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/brand-bindings", "body": { "consumerAppId": "example", "externalResourceType": "example", "externalResourceId": "example", "brandKitId": "example" } }, "effects": "May change state through PUT /api/brand-bindings. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/brand-bindings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_bindings.delete", "title": "Delete brand binding", "description": "Remove a consumer resource brand binding.", "method": "DELETE", "path": "/api/brand-bindings/{id}", "permission": "brand:write", "authorizationMode": "static", "readOnly": false, "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", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/brand-bindings/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/brand-bindings/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/brand-bindings/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kits.resolve", "title": "Resolve brand kit", "description": "Resolve the exact published brand version for a kit or consumer resource.", "method": "POST", "path": "/api/brand-kits:resolve", "permission": "brand:read", "authorizationMode": "runtime", "allowedServices": [ "topolo-design", "topolo-social-studio", "topolo-socialize" ], "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "consumerAppId": { "type": "string", "minLength": 1 }, "externalResourceType": { "type": "string", "minLength": 1 }, "externalResourceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "brandKitId": "example", "consumerAppId": "example", "externalResourceType": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "POST", "path": "/api/brand-kits:resolve", "body": { "brandKitId": "example", "consumerAppId": "example", "externalResourceType": "example" } }, "effects": "Reads state through POST /api/brand-kits:resolve without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brand-kits:resolve", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_kits.validate", "title": "Validate branded content", "description": "Check content, claims, CTAs, assets, and channel restrictions against a brand snapshot, plus the snapshot’s own logo references and palette contrast.", "method": "POST", "path": "/api/brand-kits:validate", "permission": "brand:read", "authorizationMode": "runtime", "allowedServices": [ "topolo-social-studio", "topolo-socialize" ], "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "snapshot": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "text": { "type": "string" }, "channel": { "type": "string", "minLength": 1 }, "ctaId": { "type": "string", "minLength": 1 }, "claimIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "assetIds": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "snapshot", "text" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "snapshot": {}, "text": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "POST", "path": "/api/brand-kits:validate", "body": { "snapshot": {}, "text": "example" } }, "effects": "Reads state through POST /api/brand-kits:validate without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brand-kits:validate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_assets.list", "title": "List brand assets", "description": "List registered logos, fonts, media, and templates for a kit.", "method": "GET", "path": "/api/brand-kits/{brandKitId}/assets", "permission": "brand:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "brandKitId": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand-kits/example/assets", "body": null }, "effects": "Reads state through GET /api/brand-kits/{brandKitId}/assets without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand-kits/*/assets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_assets.register", "title": "Register brand asset", "description": "Register an asset before uploading its content.", "method": "POST", "path": "/api/brand-assets", "permission": "brand:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "mimeType": { "type": "string", "minLength": 1 }, "license": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId", "kind", "name", "mimeType" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "brandKitId": "example", "kind": "example", "name": "example", "mimeType": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/brand-assets", "body": { "brandKitId": "example", "kind": "example", "name": "example", "mimeType": "example" } }, "effects": "May change state through POST /api/brand-assets. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/brand-assets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_assets.upload", "title": "Upload brand asset content", "description": "Upload base64-encoded content into a registered Brand asset.", "method": "PUT", "path": "/api/brand-assets/{assetId}/content", "permission": "brand:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "assetId": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string", "minLength": 1, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" }, "contentType": { "type": "string", "minLength": 1 }, "fileName": { "type": "string", "minLength": 1 } }, "required": [ "assetId", "contentBase64", "contentType", "fileName" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "upload": { "profile": "inline-base64", "contentField": "contentBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 26214400, "acceptedContentTypes": [ "*/*" ] } }, "documentation": { "example_input": { "assetId": "example", "contentBase64": "/example", "contentType": "example", "fileName": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/brand-assets/example/content", "body": { "assetId": "example", "contentBase64": "/example", "contentType": "example", "fileName": "example" } }, "effects": "May change state through PUT /api/brand-assets/{assetId}/content. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/brand-assets/*/content", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brand_assets.download", "title": "Download brand asset content", "description": "Read authenticated Brand asset bytes for an allowed organization-bound consumer.", "method": "GET", "path": "/api/brand-assets/{assetId}/content", "permission": "brand:read", "authorizationMode": "runtime", "allowedServices": [ "topolo-design", "topolo-social-studio", "topolo-socialize" ], "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "assetId": { "type": "string", "minLength": 1 } }, "required": [ "assetId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "contentType": { "type": "string", "minLength": 1 }, "contentLength": { "type": "integer", "minimum": 0 }, "contentBase64": { "type": "string" } }, "required": [ "contentType", "contentLength", "contentBase64" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "assetId": "example" }, "cli_example": [ "topolo actions --service topolo-brand --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand-assets/example/content", "body": null }, "effects": "Reads state through GET /api/brand-assets/{assetId}/content without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand-assets/*/content", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 33, "matched_actions": 29, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [ { "key": "DELETE /api/brand-bindings", "method": "DELETE", "path": "/api/brand-bindings", "source": "apps/api/src/brand-routes.ts", "target": "api" } ], "ignored_routes": 3, "configured_exclusions": 1, "configuration_findings": [], "notes": [ "22 manually-declared route(s)" ] }, "runtime_contract_audit": { "status": "verified", "actions": 29, "contracts": 29, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/worker.ts" ], "authorization_sources": [ "apps/api/src/worker.ts" ], "findings": [] } } ], "mobile_contracts": [], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "ALL", "path": "*", "source_path": "apps/TopoloBrand/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/health", "source_path": "apps/TopoloBrand/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/app-identity", "source_path": "apps/TopoloBrand/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/widget", "source_path": "apps/TopoloBrand/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/bootstrap", "source_path": "apps/TopoloBrand/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/privacy/export", "source_path": "apps/TopoloBrand/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/privacy", "source_path": "apps/TopoloBrand/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/privacy/retention", "source_path": "apps/TopoloBrand/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/workspaces", "source_path": "apps/TopoloBrand/apps/api/src/worker.ts" } ], "ui_routes": [ { "path": "/dashboard", "source_path": "apps/TopoloBrand/apps/web/src/App.tsx" }, { "path": "/brand-kits", "source_path": "apps/TopoloBrand/apps/web/src/App.tsx" }, { "path": "/brand-kits/:kitId/:section?", "source_path": "apps/TopoloBrand/apps/web/src/App.tsx" }, { "path": "/assets", "source_path": "apps/TopoloBrand/apps/web/src/App.tsx" }, { "path": "/publishing", "source_path": "apps/TopoloBrand/apps/web/src/App.tsx" }, { "path": "/connections", "source_path": "apps/TopoloBrand/apps/web/src/App.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloBrand/apps/web/src/App.tsx" }, { "path": "/settings", "source_path": "apps/TopoloBrand/apps/web/src/App.tsx" }, { "path": "/settings/:section", "source_path": "apps/TopoloBrand/apps/web/src/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/brand", "internal/apps/topolo-brand" ], "present_paths": [ "applications/brand", "internal/apps/topolo-brand" ], "missing_paths": [], "human_reference": "/systems/topolo-brand", "machine_reference": "/machine/systems/topolo-brand.json", "action_examples": 29, "action_schemas": 29 }, "source_findings": [ { "type": "uncatalogued_routes", "source_path": "apps/TopoloBrand/topolo.app.json", "detail": [ { "key": "DELETE /api/brand-bindings", "method": "DELETE", "path": "/api/brand-bindings", "source": "apps/api/src/brand-routes.ts", "target": "api" } ] } ] }, "topolo-bugfix": { "id": "topolo-bugfix", "name": "Improve Topolo", "slug": "topolo-bugfix", "kind": "application", "visibility": "public", "repo_paths": [ "system-apps/TopoloBugFix", "system-apps/TopoloBugFixRunner" ], "source_revisions": [ { "source_path": "system-apps/TopoloBugFix", "repository": "system-apps/TopoloBugFix", "revision": "f255bd2ae4f710130f36e8f5c6e42bd9fdac21f1", "ref": "origin/staging" }, { "source_path": "system-apps/TopoloBugFixRunner", "repository": "system-apps/TopoloBugFixRunner", "revision": "92dcf622930a7b0c034d567f8362505b448294b5", "ref": "origin/staging" } ], "source_counts": { "source_files": 45, "test_files": 37, "test_cases": 0, "migration_files": 9, "database_tables": 0, "manifests": 2, "deploy_targets": 2, "actions": 25, "mobile_contracts": 0, "notifications": 6, "package_manifests": 2, "deployment_configs": 0 }, "manifests": [ { "source_path": "system-apps/TopoloBugFix/topolo.app.json", "service_slug": "topolo-bugfix", "name": "topolo-bugfix", "app_id": "app_topolo_bugfix", "compatibility_date": "2026-04-10", "primary_target": "api", "environments": [ "development", "production", "staging" ], "targets": [ { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/index.js", "worker_name": "topolo-bugfix", "subdomain": "bugfix", "healthcheck_path": "/health", "variable_names": [ "BUGFIX_PUBLIC_BASE_URL", "ENVIRONMENT", "GITHUB_API_URL", "GITHUB_REPO_OWNER", "NEXUS_GATEWAY_URL", "PLATFORM_ADMIN_ORG_ID", "TOPOLO_APP_ID", "TOPOLO_AUTH_BASE_URL", "TOPOLO_DOCS_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "BUGFIX_REPORTS_DB", "target": null }, { "kind": "d1", "binding": "BUGFIX_FIXES_DB", "target": null }, { "kind": "d1", "binding": "BUGFIX_OPERATIONS_DB", "target": null }, { "kind": "d1", "binding": "BUGFIX_EVENTS_DB", "target": null } ] } ], "notifications": [ "bugfix.fix.applied", "bugfix.fix.approval_requested", "bugfix.fix.failed", "bugfix.fix.ready", "bugfix.queue.stalled", "bugfix.report.created" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_bugfix", "events": [ { "type": "bugfix.fix.applied", "version": 1, "description": "A BugFix pull request was durably recorded as merged.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "report_id", "app_name", "fix_id", "pull_request_number", "status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "report_id": { "type": "string", "minLength": 1 }, "app_name": { "type": "string", "minLength": 1 }, "fix_id": { "type": [ "string", "null" ] }, "job_id": { "type": [ "string", "null" ] }, "pull_request_number": { "type": "integer", "minimum": 1 }, "status": { "const": "merged" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Bug fix applied", "body": "Pull request #42 was merged.", "object_id": "fix_1", "report_id": "report_1", "app_name": "topolo-books", "fix_id": "fix_1", "pull_request_number": 42, "status": "merged", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://bugfix.stg.topolo.us/fixes/fix_1" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^bugfix:fix-applied:" } }, { "type": "bugfix.fix.approval_requested", "version": 1, "description": "A validated fix durably entered the review-pending state.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "report_id", "app_name", "fix_id", "pull_request_id", "status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "report_id": { "type": "string", "minLength": 1 }, "app_name": { "type": "string", "minLength": 1 }, "fix_id": { "type": "string", "minLength": 1 }, "pull_request_id": { "type": "string", "minLength": 1 }, "status": { "const": "review_pending" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Bug fix approval requested", "body": "A validated fix is ready for review.", "object_id": "fix_1", "report_id": "report_1", "app_name": "topolo-books", "fix_id": "fix_1", "pull_request_id": "pr_1", "status": "review_pending", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://bugfix.stg.topolo.us/fixes/fix_1" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^bugfix:fix-approval-requested:" } }, { "type": "bugfix.fix.failed", "version": 1, "description": "A fix generation job durably exhausted or entered the failed state.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "report_id", "app_name", "fix_id", "job_id", "status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "report_id": { "type": "string", "minLength": 1 }, "app_name": { "type": "string", "minLength": 1 }, "fix_id": { "type": [ "string", "null" ] }, "job_id": { "type": [ "string", "null" ] }, "status": { "const": "failed" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Bug fix failed", "body": "The external runner exhausted its fix attempts.", "object_id": "job_1", "report_id": "report_1", "app_name": "topolo-books", "fix_id": null, "job_id": "job_1", "status": "failed", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://bugfix.stg.topolo.us/reports/report_1" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^bugfix:fix-failed:" } }, { "type": "bugfix.fix.ready", "version": 1, "description": "A generated or runner-produced fix was durably recorded and is ready for its next step.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "report_id", "app_name", "fix_id", "status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "report_id": { "type": "string", "minLength": 1 }, "app_name": { "type": "string", "minLength": 1 }, "fix_id": { "type": [ "string", "null" ] }, "job_id": { "type": [ "string", "null" ] }, "confidence_score": { "type": "number", "minimum": 0, "maximum": 1 }, "status": { "enum": [ "generated", "fix_generated", "pr_created", "merged" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Bug fix ready", "body": "A proposed fix is ready for review.", "object_id": "fix_1", "report_id": "report_1", "app_name": "topolo-books", "fix_id": "fix_1", "confidence_score": 0.91, "status": "generated", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://bugfix.stg.topolo.us/fixes/fix_1" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^bugfix:fix-ready:" } }, { "type": "bugfix.queue.stalled", "version": 1, "description": "An expired runner lease was durably returned to the queued state.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "report_id", "app_name", "job_id", "runner_id", "lease_expires_at", "status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "report_id": { "type": "string", "minLength": 1 }, "app_name": { "type": "string", "minLength": 1 }, "job_id": { "type": "string", "minLength": 1 }, "runner_id": { "type": [ "string", "null" ] }, "lease_expires_at": { "type": "string", "format": "date-time" }, "status": { "const": "queued" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "BugFix queue job stalled", "body": "An expired runner lease was returned to the fix queue.", "object_id": "job_1", "report_id": "report_1", "app_name": "topolo-books", "job_id": "job_1", "runner_id": "runner_1", "lease_expires_at": "2026-07-20T00:00:00.000Z", "status": "queued", "occurred_at": "2026-07-20T00:01:00.000Z", "cta_url": "https://bugfix.stg.topolo.us/reports/report_1" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^bugfix:queue-stalled:" } }, { "type": "bugfix.report.created", "version": 1, "description": "A bug report and its triage result were durably persisted.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "report_id", "app_name", "severity", "status", "triage_tier", "fingerprint", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "report_id": { "type": "string", "minLength": 1 }, "app_name": { "type": "string", "minLength": 1 }, "severity": { "enum": [ "low", "medium", "high", "critical" ] }, "status": { "const": "pending" }, "triage_tier": { "enum": [ "tier_1", "tier_2" ] }, "fingerprint": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Bug report created", "body": "topolo-books: Invoice total is stale", "object_id": "report_1", "report_id": "report_1", "app_name": "topolo-books", "severity": "high", "status": "pending", "triage_tier": "tier_1", "fingerprint": "books:invoice-total", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://bugfix.stg.topolo.us/reports/report_1" } ], "dataClassification": "confidential", "sensitiveFields": [ "fingerprint" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^bugfix:report-created:" } } ] }, "actions": [ { "name": "widget.get", "title": "Get BugFix widget", "description": "Get the TopoloOne widget summary for BugFix.", "method": "GET", "path": "/api/widget", "permission": "issues:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "organizations.data.export", "title": "Export organization data", "description": "Export organization-authored BugFix data without credentials.", "method": "GET", "path": "/api/organizations/{organizationId}/data", "permission": "privacy:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "organizationId": "example" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/example/data", "body": null }, "effects": "Reads state through GET /api/organizations/{organizationId}/data without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.erase", "title": "Erase organization data", "description": "Erase organization-authored BugFix data after active work is stopped and literal ERASE confirmation is provided.", "method": "DELETE", "path": "/api/organizations/{organizationId}/data", "permission": "privacy:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "organizationId", "confirmation" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "organizationId": "example", "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/example/data", "body": null }, "effects": "May change state through DELETE /api/organizations/{organizationId}/data. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "reports.create", "title": "Create bug report", "description": "Create an authenticated bug report for a Topolo application.", "method": "POST", "path": "/api/actions/reports", "permission": "issues:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "appName": { "type": "string", "minLength": 1 }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "appVersion": { "type": "string" }, "pageUrl": { "type": "string" }, "userAgent": { "type": "string" }, "screenshot": { "type": "string" }, "consoleErrors": {}, "componentStack": { "type": "string" }, "additionalContext": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "title", "description", "appName" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "title": "example", "description": "example", "appName": "example" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/actions/reports", "body": { "title": "example", "description": "example", "appName": "example" } }, "effects": "May change state through POST /api/actions/reports. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/actions/reports", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "reports.list", "title": "List bug reports", "description": "List bug reports visible to the active principal.", "method": "GET", "path": "/api/reports", "permission": "issues:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "app": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "app": "example", "status": "example", "limit": 1 }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/reports", "body": null }, "effects": "Reads state through GET /api/reports without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/reports", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "reports.get", "title": "Get bug report", "description": "Get one bug report.", "method": "GET", "path": "/api/reports/{reportId}", "permission": "issues:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 } }, "required": [ "reportId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "reportId": "example" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/reports/example", "body": null }, "effects": "Reads state through GET /api/reports/{reportId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/reports/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "reports.status.get", "title": "Get bug report status", "description": "Get the current status and related fixes for one bug report.", "method": "GET", "path": "/api/reports/{reportId}/status", "permission": "issues:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 } }, "required": [ "reportId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "reportId": "example" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/reports/example/status", "body": null }, "effects": "Reads state through GET /api/reports/{reportId}/status without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/reports/*/status", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "reports.fix.generate", "title": "Generate report fix", "description": "Start AI fix generation for one bug report.", "method": "POST", "path": "/api/reports/{reportId}/fix", "permission": "runs:invoke", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 } }, "required": [ "reportId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "reportId": "example" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/reports/example/fix", "body": { "reportId": "example" } }, "effects": "May change state through POST /api/reports/{reportId}/fix. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/reports/*/fix", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "fixes.get", "title": "Get generated fix", "description": "Get one generated fix and its pull-request state.", "method": "GET", "path": "/api/fixes/{fixId}", "permission": "issues:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fixId": { "type": "string", "minLength": 1 } }, "required": [ "fixId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "fixId": "example" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/fixes/example", "body": null }, "effects": "Reads state through GET /api/fixes/{fixId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/fixes/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "fixes.approve", "title": "Approve generated fix", "description": "Approve one generated fix and merge its open pull request.", "method": "POST", "path": "/api/fixes/{fixId}/approve", "permission": "issues:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fixId": { "type": "string", "minLength": 1 } }, "required": [ "fixId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "fixId": "example" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/fixes/example/approve", "body": { "fixId": "example" } }, "effects": "May change state through POST /api/fixes/{fixId}/approve. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/fixes/*/approve", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "fixes.reject", "title": "Reject generated fix", "description": "Reject one generated fix and close its open pull request.", "method": "POST", "path": "/api/fixes/{fixId}/reject", "permission": "issues:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fixId": { "type": "string", "minLength": 1 }, "reason": { "type": "string" } }, "required": [ "fixId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "fixId": "example" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/fixes/example/reject", "body": { "fixId": "example" } }, "effects": "May change state through POST /api/fixes/{fixId}/reject. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/fixes/*/reject", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.stats.get", "title": "Get BugFix statistics", "description": "Get platform BugFix operational statistics.", "method": "GET", "path": "/api/admin/stats", "permission": "issues:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "queue.retry", "title": "Retry failed reports", "description": "Move selected failed reports back to pending.", "method": "POST", "path": "/api/admin/retry", "permission": "issues:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "reportIds" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "reportIds": [ "example" ] }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/retry", "body": { "reportIds": [ "example" ] } }, "effects": "May change state through POST /api/admin/retry. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/retry", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "queue.list", "title": "List review queue", "description": "List the platform BugFix review queue.", "method": "GET", "path": "/api/admin/queue", "permission": "issues:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "type": "string", "minLength": 1 }, "app": { "type": "string", "minLength": 1 }, "severity": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "status": "example", "app": "example", "severity": "example" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/queue", "body": null }, "effects": "Reads state through GET /api/admin/queue without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/queue", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "queue.stats.get", "title": "Get review queue statistics", "description": "Get review queue totals by state.", "method": "GET", "path": "/api/admin/queue/stats", "permission": "issues:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/queue/stats", "body": null }, "effects": "Reads state through GET /api/admin/queue/stats without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/queue/stats", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "queue.report.get", "title": "Get queued report", "description": "Get one report from the platform review queue.", "method": "GET", "path": "/api/admin/queue/{reportId}", "permission": "issues:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 } }, "required": [ "reportId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "reportId": "example" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/queue/example", "body": null }, "effects": "Reads state through GET /api/admin/queue/{reportId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/queue/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "queue.report.update", "title": "Update queued report", "description": "Update review notes, guidance, priority, target, assignment, or state.", "method": "PUT", "path": "/api/admin/queue/{reportId}", "permission": "issues:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 }, "admin_notes": { "type": "string" }, "admin_guidance": { "type": "string" }, "priority": { "type": "string" }, "target_repo": { "type": "string" }, "target_branch": { "type": "string" }, "assigned_agent": { "type": "string" }, "status": { "type": "string" } }, "required": [ "reportId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "reportId": "example" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/admin/queue/example", "body": { "reportId": "example" } }, "effects": "May change state through PUT /api/admin/queue/{reportId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/admin/queue/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "queue.report.generate", "title": "Generate queued report fix", "description": "Trigger AI fix generation for one queued report with optional guidance.", "method": "POST", "path": "/api/admin/queue/{reportId}/generate", "permission": "runs:invoke", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 }, "agent": { "type": "string" }, "additional_guidance": { "type": "string" } }, "required": [ "reportId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "reportId": "example" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/queue/example/generate", "body": { "reportId": "example" } }, "effects": "May change state through POST /api/admin/queue/{reportId}/generate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/queue/*/generate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "queue.report.dismiss", "title": "Dismiss queued report", "description": "Dismiss one queued report with an optional reason.", "method": "POST", "path": "/api/admin/queue/{reportId}/dismiss", "permission": "issues:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 }, "reason": { "type": "string" } }, "required": [ "reportId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "reportId": "example" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/queue/example/dismiss", "body": { "reportId": "example" } }, "effects": "May change state through POST /api/admin/queue/{reportId}/dismiss. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/queue/*/dismiss", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "settings.public.get", "title": "Get public BugFix settings", "description": "Get BugReporter enablement and auto-fix status.", "method": "GET", "path": "/api/settings", "permission": "issues:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/settings", "body": null }, "effects": "Reads state through GET /api/settings without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "auto_fix.get", "title": "Get auto-fix state", "description": "Get the current auto-fix kill-switch state and recent changes.", "method": "GET", "path": "/api/admin/auto-fix", "permission": "bugfix:admin", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/auto-fix", "body": null }, "effects": "Reads state through GET /api/admin/auto-fix without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/auto-fix", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "auto_fix.toggle", "title": "Toggle auto-fix", "description": "Enable or disable the manual auto-fix switch.", "method": "POST", "path": "/api/admin/auto-fix/toggle", "permission": "bugfix:admin", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "enabled": { "type": "boolean" }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "enabled" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "enabled": true }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/auto-fix/toggle", "body": { "enabled": true } }, "effects": "May change state through POST /api/admin/auto-fix/toggle. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/auto-fix/toggle", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.settings.list", "title": "List BugFix settings", "description": "List all platform BugFix settings.", "method": "GET", "path": "/api/admin/settings", "permission": "bugfix:admin", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/settings", "body": null }, "effects": "Reads state through GET /api/admin/settings without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.settings.update", "title": "Update BugFix setting", "description": "Update one platform BugFix setting.", "method": "PUT", "path": "/api/admin/settings/{key}", "permission": "bugfix:admin", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "anyOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "number" } ] } }, "required": [ "key", "value" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "key": "example", "value": "example" }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/admin/settings/example", "body": { "key": "example", "value": "example" } }, "effects": "May change state through PUT /api/admin/settings/{key}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/admin/settings/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.settings.bulk_update", "title": "Bulk update BugFix settings", "description": "Update multiple platform BugFix settings atomically from one request.", "method": "POST", "path": "/api/admin/settings/bulk", "permission": "bugfix:admin", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "number" } ] } } }, "required": [ "settings" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "settings": {} }, "cli_example": [ "topolo actions --service topolo-bugfix --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/settings/bulk", "body": { "settings": {} } }, "effects": "May change state through POST /api/admin/settings/bulk. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/settings/bulk", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 37, "matched_actions": 25, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 12, "configured_exclusions": 9, "configuration_findings": [], "notes": [ "32 manually-declared route(s)" ] }, "runtime_contract_audit": { "status": "verified", "actions": 25, "contracts": 25, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/index.js" ], "authorization_sources": [ "apps/api/src/index.js" ], "findings": [] } }, { "source_path": "system-apps/TopoloBugFixRunner/topolo.app.json", "service_slug": "topolo-bugfix", "name": "topolo-bugfix-runner", "app_id": "app_topolo_bugfix_runner", "compatibility_date": null, "primary_target": null, "environments": [ "production", "staging" ], "targets": [ { "name": "runner", "kind": "none", "directory": "apps/runner", "main": null, "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": [] } } ], "mobile_contracts": [], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "ALL", "path": "*", "source_path": "system-apps/TopoloBugFix/apps/api/src/index.js" } ], "ui_routes": [ { "path": "/fixes/${fixId}", "source_path": "system-apps/TopoloBugFix/apps/api/src/controllers/fixes.js" }, { "path": "/reports/${reportId}", "source_path": "system-apps/TopoloBugFix/apps/api/src/controllers/fixes.js" }, { "path": "/reports/${report.id}", "source_path": "system-apps/TopoloBugFix/apps/api/src/controllers/reports.js" }, { "path": "/reports/${job.report_id}", "source_path": "system-apps/TopoloBugFix/apps/api/src/controllers/runner.js" }, { "path": "/fixes/${pr.fix_id}", "source_path": "system-apps/TopoloBugFix/apps/api/src/controllers/webhooks.js" }, { "path": "/reports/${job.report_id}", "source_path": "system-apps/TopoloBugFix/apps/api/src/services/fix-jobs.js" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/bugfix", "internal/apps/bugfix", "internal/runbooks/bugfix-kill-switch", "internal/runbooks/bugfix-logpush" ], "present_paths": [ "applications/bugfix", "internal/apps/bugfix", "internal/runbooks/bugfix-kill-switch", "internal/runbooks/bugfix-logpush" ], "missing_paths": [], "human_reference": "/systems/topolo-bugfix", "machine_reference": "/machine/systems/topolo-bugfix.json", "action_examples": 25, "action_schemas": 25 }, "source_findings": [] }, "topolo-bytes": { "id": "topolo-bytes", "name": "Bytes", "slug": "topolo-bytes", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloBytes" ], "source_revisions": [ { "source_path": "apps/TopoloBytes", "repository": "apps/TopoloBytes", "revision": "a91022036b05b981e179e035971d2c85a4d04f7e", "ref": "origin/staging" } ], "source_counts": { "source_files": 222, "test_files": 88, "test_cases": 0, "migration_files": 0, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 30, "mobile_contracts": 1, "notifications": 6, "package_manifests": 4, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloBytes/topolo.app.json", "service_slug": "topolo-bytes", "name": "topolo-bytes", "app_id": "app_topolo_bytes", "compatibility_date": "2026-04-10", "primary_target": null, "environments": [ "production", "staging" ], "targets": [ { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-bytes", "subdomain": "bytes", "healthcheck_path": null, "variable_names": [ "AUTH_API_URL", "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null } ] }, { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/index.ts", "worker_name": "topolo-bytes-api", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "AUTH_BASE_URL", "BYTES_QUOTA_BYTES", "BYTES_QUOTA_WARNING_PERCENT", "ENVIRONMENT", "NEXUS_GATEWAY_URL", "R2_BUCKET_NAME", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "r2", "binding": "BYTES_BUCKET", "target": null }, { "kind": "kv", "binding": "SHARE_LINKS", "target": null }, { "kind": "vectorize", "binding": "VEC", "target": null }, { "kind": "vectorize", "binding": "VEC", "target": null } ] } ], "notifications": [ "bytes.processing.failed", "bytes.quota.warning", "bytes.share.created", "bytes.share.expiring", "bytes.upload.completed", "bytes.upload.failed" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_bytes", "events": [ { "type": "bytes.processing.failed", "version": 1, "description": "A durable Bytes media-processing attempt failed and was persisted for retry and review.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "file_key", "stage", "reason", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "file_key": { "type": "string", "minLength": 1 }, "stage": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "File processing failed", "body": "launch-video.mp4 could not complete video processing.", "object_id": "failure_123", "file_key": "launch-video.mp4", "stage": "video_processing", "reason": "Stream processing rejected the file", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^bytes:processing-failed:" }, "sensitiveFields": [] }, { "type": "bytes.quota.warning", "version": 1, "description": "A Bytes workspace crossed its configured storage quota warning threshold.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "used_bytes", "quota_bytes", "warning_percent", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "used_bytes": { "type": "integer", "minimum": 0 }, "quota_bytes": { "type": "integer", "minimum": 1 }, "warning_percent": { "type": "number", "minimum": 1, "maximum": 100 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Bytes storage quota warning", "body": "Storage usage has reached 80% of the workspace quota.", "object_id": "workspace_123", "used_bytes": 85899345920, "quota_bytes": 107374182400, "warning_percent": 80, "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^bytes:quota-warning:" }, "sensitiveFields": [] }, { "type": "bytes.share.created", "version": 1, "description": "A file share link was created.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "thread_key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "A file share link was created.", "body": "Open the owning app to review this event.", "object_id": "object_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^bytes:share-created:" }, "sensitiveFields": [] }, { "type": "bytes.share.expiring", "version": 1, "description": "A persisted Bytes share entered its final 24-hour availability window.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "expires_at", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "expires_at": { "type": "string", "format": "date-time" }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Bytes share expiring soon", "body": "Your Bytes share expires at 2026-07-21T00:00:00.000Z.", "object_id": "share_123", "expires_at": "2026-07-21T00:00:00.000Z", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^bytes:share-expiring:" }, "sensitiveFields": [] }, { "type": "bytes.upload.completed", "version": 1, "description": "A direct or multipart upload was durably committed to the workspace bucket.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "file_key", "etag", "size_bytes", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "file_key": { "type": "string", "minLength": 1 }, "etag": { "type": "string", "minLength": 1 }, "size_bytes": { "type": [ "integer", "null" ], "minimum": 0 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Upload completed", "body": "launch-video.mp4 is ready in Bytes.", "object_id": "organizations/org_123/workspaces/workspace_123/launch-video.mp4", "file_key": "launch-video.mp4", "etag": "etag_123", "size_bytes": 4096, "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^bytes:upload-completed:" }, "sensitiveFields": [] }, { "type": "bytes.upload.failed", "version": 1, "description": "A failed direct or multipart upload attempt was durably recorded for retry and review.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "file_key", "reason", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "file_key": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Upload failed", "body": "launch-video.mp4 could not be uploaded.", "object_id": "failure_123", "file_key": "launch-video.mp4", "reason": "R2 rejected the upload", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^bytes:upload-failed:" }, "sensitiveFields": [] } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "files:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "files.list", "title": "List files", "description": "List files and folders.", "method": "GET", "path": "/api/list", "permission": "files:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "prefix": { "type": "string" }, "cursor": { "type": "string" }, "fileType": { "type": "string" }, "sizeMin": { "type": "string" }, "sizeMax": { "type": "string" }, "dateFrom": { "type": "string" }, "dateTo": { "type": "string" }, "durationMin": { "type": "string" }, "durationMax": { "type": "string" }, "search": { "type": "string" }, "sortBy": { "type": "string" }, "sortOrder": { "type": "string" }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List files.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "prefix": "example", "cursor": "example", "fileType": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/list", "body": null }, "effects": "Reads state through GET /api/list without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/list", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "files.search", "title": "Search files", "description": "Search files by metadata or content.", "method": "GET", "path": "/api/search", "permission": "files:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "prefix": { "type": "string" }, "cursor": { "type": "string" }, "fileType": { "type": "string" }, "sizeMin": { "type": "string" }, "sizeMax": { "type": "string" }, "dateFrom": { "type": "string" }, "dateTo": { "type": "string" }, "durationMin": { "type": "string" }, "durationMax": { "type": "string" }, "search": { "type": "string" }, "sortBy": { "type": "string" }, "sortOrder": { "type": "string" }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Search files.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "prefix": "example", "cursor": "example", "fileType": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/search", "body": null }, "effects": "Reads state through GET /api/search without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/search", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "files.upload_url.create", "title": "Create upload URL", "description": "Create a signed upload URL for a file.", "method": "POST", "path": "/api/upload-url", "permission": "files:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 104857600 }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key", "type", "size" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create upload URL.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "upload": { "profile": "url-session", "fileNameField": "key", "contentTypeField": "type", "sizeField": "size", "maxBytes": 104857600, "acceptedContentTypes": [ "*/*" ], "uploadUrlPath": "url", "uploadMethod": "PUT" } }, "documentation": { "example_input": { "key": "example", "type": "example", "size": 1 }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/upload-url", "body": { "key": "example", "type": "example", "size": 1 } }, "effects": "May change state through POST /api/upload-url. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/upload-url", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "files.rename", "title": "Rename file", "description": "Rename a file.", "method": "POST", "path": "/api/rename", "permission": "files:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "oldKey": { "type": "string", "minLength": 1 }, "newKey": { "type": "string", "minLength": 1 }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "oldKey", "newKey" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Rename file.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "oldKey": "example", "newKey": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/rename", "body": { "oldKey": "example", "newKey": "example" } }, "effects": "May change state through POST /api/rename. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/rename", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "shares.list", "title": "List shares", "description": "List file sharing links.", "method": "GET", "path": "/api/shares", "permission": "sharing:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List shares.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "cursor": "example", "limit": 1, "scope": "org" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/shares", "body": null }, "effects": "Reads state through GET /api/shares without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/shares", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "shares.create", "title": "Create share", "description": "Create a sharing link.", "method": "POST", "path": "/api/shares/create", "permission": "sharing:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "permissions": { "type": "string", "enum": [ "view", "download" ] }, "shareType": { "type": "string", "enum": [ "single", "multiple", "zip" ] }, "password": { "type": "string" }, "expirationDays": { "type": "number" }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "fileKeys", "permissions", "shareType" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create share.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "fileKeys": [ "example" ], "permissions": "view", "shareType": "single" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/shares/create", "body": { "fileKeys": [ "example" ], "permissions": "view", "shareType": "single" } }, "effects": "May change state through POST /api/shares/create. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/shares/create", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "bulk.organize", "title": "Bulk organize files", "description": "Run bulk file organization.", "method": "POST", "path": "/api/bulk/organize", "permission": "pipelines:invoke", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileKeys": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "rules": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "by-date", "by-type", "by-size", "custom" ] }, "pattern": { "type": "string" }, "conditions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": false }, "dryRun": { "type": "boolean" }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "rules" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Bulk organize files.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "rules": { "type": "by-date" } }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/bulk/organize", "body": { "rules": { "type": "by-date" } } }, "effects": "May change state through POST /api/bulk/organize. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/bulk/organize", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "shares.refresh_session", "title": "Shares Refresh Session", "description": "Call POST /api/shares/refresh-session.", "method": "POST", "path": "/api/shares/refresh-session", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "shareId": { "type": "string", "minLength": 1 }, "fileKey": { "type": "string", "minLength": 1 } }, "required": [ "shareId", "fileKey" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Shares Refresh Session.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "public", "documentation": { "example_input": { "shareId": "example", "fileKey": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/shares/refresh-session", "body": { "shareId": "example", "fileKey": "example" } }, "effects": "May change state through POST /api/shares/refresh-session. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/shares/refresh-session", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "shares.delete", "title": "Shares Delete", "description": "Call DELETE /api/shares/{shareId}.", "method": "DELETE", "path": "/api/shares/{shareId}", "permission": "sharing:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "shareId": { "type": "string", "minLength": 1 } }, "required": [ "shareId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Shares Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "shareId": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/shares/example", "body": null }, "effects": "May change state through DELETE /api/shares/{shareId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/shares/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "desktop.releases.latest", "title": "Desktop Releases Latest", "description": "Call GET /api/desktop/releases/latest.", "method": "GET", "path": "/api/desktop/releases/latest", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Desktop Releases Latest.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "public", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/desktop/releases/latest", "body": null }, "effects": "Reads state through GET /api/desktop/releases/latest without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/desktop/releases/latest", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "desktop.download", "title": "Desktop Download", "description": "Call GET /api/desktop/download.", "method": "GET", "path": "/api/desktop/download", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 } }, "required": [ "key" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Desktop Download.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "public", "documentation": { "example_input": { "key": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/desktop/download", "body": null }, "effects": "Reads state through GET /api/desktop/download without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/desktop/download", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "uploads.multipart.create", "title": "Uploads Multipart Create", "description": "Call POST /api/multipart/create.", "method": "POST", "path": "/api/multipart/create", "permission": "files:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "contentType": { "type": "string" }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Uploads Multipart Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "key": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/multipart/create", "body": { "key": "example" } }, "effects": "May change state through POST /api/multipart/create. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/multipart/create", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "uploads.multipart.sign", "title": "Uploads Multipart Sign", "description": "Call POST /api/multipart/sign.", "method": "POST", "path": "/api/multipart/sign", "permission": "files:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "uploadId": { "type": "string", "minLength": 1 }, "partNumbers": { "minItems": 1, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key", "uploadId", "partNumbers" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Uploads Multipart Sign.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "key": "example", "uploadId": "example", "partNumbers": [ 1 ] }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/multipart/sign", "body": { "key": "example", "uploadId": "example", "partNumbers": [ 1 ] } }, "effects": "May change state through POST /api/multipart/sign. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/multipart/sign", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "uploads.multipart.complete", "title": "Uploads Multipart Complete", "description": "Call POST /api/multipart/complete.", "method": "POST", "path": "/api/multipart/complete", "permission": "files:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "uploadId": { "type": "string", "minLength": 1 }, "parts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1, "maximum": 10000 }, "etag": { "type": "string", "minLength": 1 } }, "required": [ "partNumber", "etag" ], "additionalProperties": false } }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key", "uploadId", "parts" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Uploads Multipart Complete.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "key": "example", "uploadId": "example", "parts": [ { "partNumber": 1, "etag": "example" } ] }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/multipart/complete", "body": { "key": "example", "uploadId": "example", "parts": [ { "partNumber": 1, "etag": "example" } ] } }, "effects": "May change state through POST /api/multipart/complete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/multipart/complete", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "uploads.multipart.abort", "title": "Uploads Multipart Abort", "description": "Call POST /api/multipart/abort.", "method": "POST", "path": "/api/multipart/abort", "permission": "files:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "uploadId": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key", "uploadId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Uploads Multipart Abort.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "key": "example", "uploadId": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/multipart/abort", "body": { "key": "example", "uploadId": "example" } }, "effects": "May change state through POST /api/multipart/abort. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/multipart/abort", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "files.delete_route", "title": "Files Delete Route", "description": "Call DELETE /api/delete.", "method": "DELETE", "path": "/api/delete", "permission": "files:delete", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "files": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "files" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Files Delete Route.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "files": [ "example" ] }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/delete", "body": null }, "effects": "May change state through DELETE /api/delete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/delete", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "files.bulk_rename", "title": "Files Bulk Rename", "description": "Call POST /api/bulk/rename.", "method": "POST", "path": "/api/bulk/rename", "permission": "files:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "pattern": { "type": "string", "minLength": 1 }, "options": { "type": "object", "properties": { "startIndex": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "findText": { "type": "string" }, "replaceText": { "type": "string" }, "addTimestamp": { "type": "boolean" }, "preserveExtension": { "type": "boolean" } }, "additionalProperties": false }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "fileKeys", "pattern" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Files Bulk Rename.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "fileKeys": [ "example" ], "pattern": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/bulk/rename", "body": { "fileKeys": [ "example" ], "pattern": "example" } }, "effects": "May change state through POST /api/bulk/rename. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/bulk/rename", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "folders.create_alt", "title": "Folders Create Alt", "description": "Call POST /api/folders/create.", "method": "POST", "path": "/api/folders/create", "permission": "folders:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folderPath": { "type": "string", "minLength": 1 }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "folderPath" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Folders Create Alt.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "folderPath": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/folders/create", "body": { "folderPath": "example" } }, "effects": "May change state through POST /api/folders/create. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/folders/create", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "folder.rename_alt", "title": "Folder Rename Alt", "description": "Call PUT /api/folder/rename.", "method": "PUT", "path": "/api/folder/rename", "permission": "folders:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "oldPath": { "type": "string", "minLength": 1 }, "newPath": { "type": "string", "minLength": 1 }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "oldPath", "newPath" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Folder Rename Alt.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "oldPath": "example", "newPath": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/folder/rename", "body": { "oldPath": "example", "newPath": "example" } }, "effects": "May change state through PUT /api/folder/rename. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/folder/rename", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "folder.delete_alt", "title": "Folder Delete Alt", "description": "Call DELETE /api/folder/delete.", "method": "DELETE", "path": "/api/folder/delete", "permission": "files:delete", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "object", "properties": { "folderPath": { "type": "string", "minLength": 1 }, "force": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "folderPath" ], "additionalProperties": false } }, "required": [ "query" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Folder Delete Alt.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "query": { "folderPath": "example" } }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/folder/delete", "body": null }, "effects": "May change state through DELETE /api/folder/delete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/folder/delete", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "folder.info.get", "title": "Folder Info Get", "description": "Call GET /api/folder/info.", "method": "GET", "path": "/api/folder/info", "permission": "folders:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folderPath": { "type": "string" }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Folder Info Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "folderPath": "example", "bucket": "example", "scope": "org" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/folder/info", "body": null }, "effects": "Reads state through GET /api/folder/info without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/folder/info", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "files.move", "title": "Files Move", "description": "Call POST /api/files/move.", "method": "POST", "path": "/api/files/move", "permission": "files:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "targetFolder": { "type": "string" }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "fileKeys", "targetFolder" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Files Move.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "fileKeys": [ "example" ], "targetFolder": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/files/move", "body": { "fileKeys": [ "example" ], "targetFolder": "example" } }, "effects": "May change state through POST /api/files/move. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/files/move", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "files.update", "title": "Files Update", "description": "Call PUT /api/file/update.", "method": "PUT", "path": "/api/file/update", "permission": "files:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key", "content" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Files Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "key": "example", "content": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/file/update", "body": { "key": "example", "content": "example" } }, "effects": "May change state through PUT /api/file/update. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/file/update", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "files.content.update", "title": "Files Content Update", "description": "Call PUT /api/file-content.", "method": "PUT", "path": "/api/file-content", "permission": "files:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key", "content" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Files Content Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "key": "example", "content": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/file-content", "body": { "key": "example", "content": "example" } }, "effects": "May change state through PUT /api/file-content. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/file-content", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "download.signed_url.create", "title": "Download Signed Url Create", "description": "Call POST /api/download/signed-url.", "method": "POST", "path": "/api/download/signed-url", "permission": "files:read", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] }, "expirationMinutes": { "type": "number" }, "downloadFilename": { "type": "string" } }, "required": [ "key" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Download Signed Url Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "key": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/download/signed-url", "body": { "key": "example" } }, "effects": "May change state through POST /api/download/signed-url. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/download/signed-url", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "video.mark_range_incompatible", "title": "Video Mark Range Incompatible", "description": "Call POST /api/video/mark-range-incompatible.", "method": "POST", "path": "/api/video/mark-range-incompatible", "permission": "media:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Video Mark Range Incompatible.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "key": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/video/mark-range-incompatible", "body": { "key": "example" } }, "effects": "May change state through POST /api/video/mark-range-incompatible. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/video/mark-range-incompatible", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "Delete workspace", "description": "Delete a non-default empty Bytes storage workspace.", "readOnly": false, "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "method": "DELETE", "path": "/api/workspaces/{workspaceId}", "permission": "workspace:delete", "authorizationMode": "static", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "target": "api", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.data.export", "title": "Export workspace data", "description": "Export a portable inventory of files and redacted share-link metadata for a Bytes workspace.", "readOnly": true, "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "method": "GET", "path": "/api/workspaces/{workspaceId}/export", "permission": "storage:read", "authorizationMode": "static", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "target": "api", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/export", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceId}/export without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/export", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.data.erase", "title": "Erase workspace data", "description": "Permanently erase files, semantic vectors, and share links owned by a Bytes workspace.", "readOnly": false, "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "method": "DELETE", "path": "/api/workspaces/{workspaceId}/data", "permission": "workspace:delete", "authorizationMode": "static", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "target": "api", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-bytes --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/workspaces/example/data", "body": null }, "effects": "May change state through DELETE /api/workspaces/{workspaceId}/data. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/workspaces/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 41, "matched_actions": 30, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 11, "configured_exclusions": 10, "configuration_findings": [], "notes": [] }, "runtime_contract_audit": { "status": "verified", "actions": 30, "contracts": 30, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/index.ts" ], "authorization_sources": [ "apps/api/src/index.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloBytes/topolo.mobile-experience.json", "contract": { "version": "1.0.0", "status": "published", "mode": "native_capability", "appId": "app_topolo_bytes", "localizationNamespace": "bytes", "permissions": [ "files:read", "sharing:read" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/files", "auth": { "audience": "topolo-bytes", "scopes": [ "files:read", "sharing:read" ] }, "routes": [ { "path": "/files", "apiPath": "/api/list", "title": "Files", "titleKey": "bytes.mobile.routes.files.title", "template": "record.list", "dataSource": "bytes.files.list" }, { "path": "/shares", "apiPath": "/api/shares", "title": "Shares", "titleKey": "bytes.mobile.routes.shares.title", "template": "record.list", "dataSource": "bytes.shares.list" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "OPTIONS", "path": "*", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "GET", "path": "/health", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "ALL", "path": "/share/*", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/shares", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/shares/*", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/shares/refresh-session", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "ALL", "path": "/api/signed-download", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "ALL", "path": "/api/signed-download/*", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/desktop/releases/latest", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/desktop/download", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/desktop/update/:target/:arch/:current", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/widget", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "DELETE", "path": "/api/workspaces/:workspaceId", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/workspaces/:workspaceId/export", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "DELETE", "path": "/api/workspaces/:workspaceId/data", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "PUT", "path": "/api/upload/*", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/upload-url", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/multipart/create", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/multipart/sign", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/multipart/complete", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/multipart/abort", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/list", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/search", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "ALL", "path": "/api/thumbnail/*", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "DELETE", "path": "/api/delete", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/rename", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/bulk/rename", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/bulk/organize", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/folders/create", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "PUT", "path": "/api/folder/rename", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "DELETE", "path": "/api/folder/delete", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/folder/info", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/files/move", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "PUT", "path": "/api/file/update", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "PUT", "path": "/api/file-content", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/shares/create", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "DELETE", "path": "/api/shares/*", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "ALL", "path": "/share-download/*", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "ALL", "path": "/public-download/*", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "ALL", "path": "/download/*", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/download/signed-url", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/video/mark-range-incompatible", "source_path": "apps/TopoloBytes/apps/api/src/index.ts" } ], "ui_routes": [], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "internal/apps/bytes", "applications/bytes" ], "present_paths": [ "internal/apps/bytes", "applications/bytes" ], "missing_paths": [], "human_reference": "/systems/topolo-bytes", "machine_reference": "/machine/systems/topolo-bytes.json", "action_examples": 30, "action_schemas": 30 }, "source_findings": [] }, "topolo-calendar": { "id": "topolo-calendar", "name": "Calendar", "slug": "topolo-calendar", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloCalendar" ], "source_revisions": [ { "source_path": "apps/TopoloCalendar", "repository": "apps/TopoloCalendar", "revision": "9e1b270431375af5b343e06176b64696084f5baf", "ref": "origin/staging" } ], "source_counts": { "source_files": 97, "test_files": 70, "test_cases": 0, "migration_files": 13, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 32, "mobile_contracts": 1, "notifications": 9, "package_manifests": 1, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloCalendar/topolo.app.json", "service_slug": "topolo-calendar", "name": "topolo-calendar", "app_id": "app_topolo_calendar", "compatibility_date": "2026-05-01", "primary_target": "web", "environments": [ "development", "production", "staging" ], "targets": [ { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/index.ts", "worker_name": "topolo-calendar-api", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "CALENDAR_PUBLIC_BASE_URL", "CLOUDFLARE_ACCOUNT_ID", "ENVIRONMENT", "NEXUS_GATEWAY_URL", "TOPOLO_AUTH_BASE_URL", "TOPOLO_CHAT_URL", "TOPOLO_NOTIFY_URL", "TURNSTILE_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "CALENDAR_DIRECTORY_DB", "target": null }, { "kind": "d1", "binding": "CALENDAR_BOOKING_DB", "target": null }, { "kind": "r2", "binding": "CALENDAR_AVATARS", "target": null }, { "kind": "durableObjects", "binding": "CALENDAR_HOST", "target": null }, { "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 } ] }, { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/index.ts", "worker_name": "topolo-calendar", "subdomain": "calendar", "healthcheck_path": "/health", "variable_names": [ "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null } ] } ], "notifications": [ "calendar.availability.conflict_detected", "calendar.booking.approval_requested", "calendar.booking.cancelled", "calendar.booking.confirmed", "calendar.booking.invite_requested", "calendar.booking.reminder_due", "calendar.booking.request_received", "calendar.booking.updated", "calendar.external_sync.failed" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_calendar", "events": [ { "type": "calendar.availability.conflict_detected", "version": 1, "description": "A requested booking window was rejected because durable Calendar availability state reported a conflict.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string" }, "dedupe_key": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "Availability conflict: Intro Call", "body": "The requested Intro Call time overlaps an existing calendar commitment.", "object_id": "bkg_123", "occurred_at": "2026-07-20T08:55:00.000Z", "payload": { "host_id": "hst_123", "event_type_id": "evt_123", "event_name": "Intro Call", "booking_id": "bkg_123", "start_at": "2026-07-20T09:00:00.000Z", "end_at": "2026-07-20T09:30:00.000Z", "source": "public_reschedule" } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^calendar:availability-conflict:" }, "sensitiveFields": [] }, { "type": "calendar.booking.approval_requested", "version": 1, "description": "A host must review a booking request before confirmation.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "thread_key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "A host must review a booking request before confirmation.", "body": "Open the owning app to review this event.", "object_id": "object_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^calendar:booking:" } }, { "type": "calendar.booking.cancelled", "version": 1, "description": "A confirmed booking was cancelled and the invitee cancellation delivery was requested.", "status": "published", "payloadSchema": { "type": "object", "required": [ "booking_id", "recipient_email", "recipient_name", "host_name", "event_name", "start_at", "end_at", "timezone" ], "properties": { "booking_id": { "type": "string", "minLength": 1 }, "calendar_uid": { "type": "string" }, "sequence": { "type": "integer", "minimum": 0 }, "recipient_email": { "type": "string", "format": "email" }, "recipient_name": { "type": "string", "minLength": 1 }, "host_name": { "type": "string", "minLength": 1 }, "event_name": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "location_label": { "type": "string" }, "meeting_url": { "type": "string", "format": "uri" }, "manage_url": { "type": "string", "format": "uri" }, "cancel_reason": { "type": "string" }, "attendees": { "type": "array", "items": { "type": "object" } }, "ics_filename": { "type": "string" }, "ics_content": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "booking_id": "bkg_123", "recipient_email": "invitee@example.com", "recipient_name": "Invitee Person", "host_name": "Calendar Host", "event_name": "Intro Call", "start_at": "2026-07-20T09:00:00.000Z", "end_at": "2026-07-20T09:30:00.000Z", "timezone": "UTC" } ], "dataClassification": "confidential", "recipients": { "modes": [ "external" ], "externalAddress": "required" }, "idempotency": { "required": true, "pattern": "^calendar:booking:" }, "sensitiveFields": [ "recipient_email", "recipient_name" ] }, { "type": "calendar.booking.confirmed", "version": 1, "description": "A booking was confirmed for its host.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "thread_key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "A booking was confirmed for its host.", "body": "Open the owning app to review this event.", "object_id": "object_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^calendar:booking:" }, "sensitiveFields": [] }, { "type": "calendar.booking.invite_requested", "version": 1, "description": "A confirmed booking requested its initial calendar invite delivery to the invitee.", "status": "published", "payloadSchema": { "type": "object", "required": [ "booking_id", "recipient_email", "recipient_name", "host_name", "event_name", "start_at", "end_at", "timezone" ], "properties": { "booking_id": { "type": "string", "minLength": 1 }, "calendar_uid": { "type": "string" }, "sequence": { "type": "integer", "minimum": 0 }, "recipient_email": { "type": "string", "format": "email" }, "recipient_name": { "type": "string", "minLength": 1 }, "host_name": { "type": "string", "minLength": 1 }, "event_name": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "location_label": { "type": "string" }, "meeting_url": { "type": "string", "format": "uri" }, "manage_url": { "type": "string", "format": "uri" }, "cancel_reason": { "type": "string" }, "attendees": { "type": "array", "items": { "type": "object" } }, "ics_filename": { "type": "string" }, "ics_content": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "booking_id": "bkg_123", "recipient_email": "invitee@example.com", "recipient_name": "Invitee Person", "host_name": "Calendar Host", "event_name": "Intro Call", "start_at": "2026-07-20T09:00:00.000Z", "end_at": "2026-07-20T09:30:00.000Z", "timezone": "UTC" } ], "dataClassification": "confidential", "recipients": { "modes": [ "external" ], "externalAddress": "required" }, "idempotency": { "required": true, "pattern": "^calendar:booking:" }, "sensitiveFields": [ "recipient_email", "recipient_name" ] }, { "type": "calendar.booking.reminder_due", "version": 1, "description": "A confirmed booking reached its scheduled reminder delivery time.", "status": "published", "payloadSchema": { "type": "object", "required": [ "booking_id", "recipient_email", "recipient_name", "host_name", "event_name", "start_at", "end_at", "timezone" ], "properties": { "booking_id": { "type": "string", "minLength": 1 }, "calendar_uid": { "type": "string" }, "sequence": { "type": "integer", "minimum": 0 }, "recipient_email": { "type": "string", "format": "email" }, "recipient_name": { "type": "string", "minLength": 1 }, "host_name": { "type": "string", "minLength": 1 }, "event_name": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "location_label": { "type": "string" }, "meeting_url": { "type": "string", "format": "uri" }, "manage_url": { "type": "string", "format": "uri" }, "cancel_reason": { "type": "string" }, "attendees": { "type": "array", "items": { "type": "object" } }, "ics_filename": { "type": "string" }, "ics_content": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "booking_id": "bkg_123", "recipient_email": "invitee@example.com", "recipient_name": "Invitee Person", "host_name": "Calendar Host", "event_name": "Intro Call", "start_at": "2026-07-20T09:00:00.000Z", "end_at": "2026-07-20T09:30:00.000Z", "timezone": "UTC" } ], "dataClassification": "confidential", "recipients": { "modes": [ "external" ], "externalAddress": "required" }, "idempotency": { "required": true, "pattern": "^calendar:booking:" }, "sensitiveFields": [ "recipient_email", "recipient_name" ] }, { "type": "calendar.booking.request_received", "version": 1, "description": "A pending booking request was durably accepted and its requester receipt was requested.", "status": "published", "payloadSchema": { "type": "object", "required": [ "booking_id", "recipient_email", "recipient_name", "host_name", "event_name", "start_at", "end_at", "timezone" ], "properties": { "booking_id": { "type": "string", "minLength": 1 }, "calendar_uid": { "type": "string" }, "sequence": { "type": "integer", "minimum": 0 }, "recipient_email": { "type": "string", "format": "email" }, "recipient_name": { "type": "string", "minLength": 1 }, "host_name": { "type": "string", "minLength": 1 }, "event_name": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "location_label": { "type": "string" }, "meeting_url": { "type": "string", "format": "uri" }, "manage_url": { "type": "string", "format": "uri" }, "cancel_reason": { "type": "string" }, "attendees": { "type": "array", "items": { "type": "object" } }, "ics_filename": { "type": "string" }, "ics_content": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "booking_id": "bkg_123", "recipient_email": "invitee@example.com", "recipient_name": "Invitee Person", "host_name": "Calendar Host", "event_name": "Intro Call", "start_at": "2026-07-20T09:00:00.000Z", "end_at": "2026-07-20T09:30:00.000Z", "timezone": "UTC" } ], "dataClassification": "confidential", "recipients": { "modes": [ "external" ], "externalAddress": "required" }, "idempotency": { "required": true, "pattern": "^calendar:booking:" }, "sensitiveFields": [ "recipient_email", "recipient_name" ] }, { "type": "calendar.booking.updated", "version": 1, "description": "A confirmed booking changed and requested an updated calendar invite delivery to the invitee.", "status": "published", "payloadSchema": { "type": "object", "required": [ "booking_id", "recipient_email", "recipient_name", "host_name", "event_name", "start_at", "end_at", "timezone" ], "properties": { "booking_id": { "type": "string", "minLength": 1 }, "calendar_uid": { "type": "string" }, "sequence": { "type": "integer", "minimum": 0 }, "recipient_email": { "type": "string", "format": "email" }, "recipient_name": { "type": "string", "minLength": 1 }, "host_name": { "type": "string", "minLength": 1 }, "event_name": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "location_label": { "type": "string" }, "meeting_url": { "type": "string", "format": "uri" }, "manage_url": { "type": "string", "format": "uri" }, "cancel_reason": { "type": "string" }, "attendees": { "type": "array", "items": { "type": "object" } }, "ics_filename": { "type": "string" }, "ics_content": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "booking_id": "bkg_123", "recipient_email": "invitee@example.com", "recipient_name": "Invitee Person", "host_name": "Calendar Host", "event_name": "Intro Call", "start_at": "2026-07-20T09:00:00.000Z", "end_at": "2026-07-20T09:30:00.000Z", "timezone": "UTC" } ], "dataClassification": "confidential", "recipients": { "modes": [ "external" ], "externalAddress": "required" }, "idempotency": { "required": true, "pattern": "^calendar:booking:" }, "sensitiveFields": [ "recipient_email", "recipient_name" ] }, { "type": "calendar.external_sync.failed", "version": 1, "description": "A connected external calendar sync failed after Calendar durably recorded the connection error.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string" }, "dedupe_key": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "Calendar sync failed: Work calendar", "body": "Calendar could not refresh this external calendar. Reconnect it or retry the sync.", "object_id": "ext_123", "occurred_at": "2026-07-20T08:55:00.000Z", "payload": { "external_calendar_id": "ext_123", "provider": "google", "account_email": "host@example.com", "reason": "provider unavailable", "failed_at": "2026-07-20T08:55:00.000Z" } } ], "dataClassification": "confidential", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^calendar:external-sync:" }, "sensitiveFields": [ "payload.account_email" ] } ] }, "actions": [ { "name": "privacy.export", "title": "Export organization Calendar data", "description": "Export portable Calendar-owned data for the authenticated organization.", "method": "GET", "path": "/api/privacy", "permission": "privacy:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "outputSchema": { "type": "object", "title": "Export organization Calendar data response", "description": "Operation result returned by privacy.export.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "privacy record", "properties": { "id": { "type": "string", "description": "Stable identifier when the privacy exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=privacy.export", "resource": { "kind": "privacy", "idPath": "$.id" }, "effects": [ "Reads privacy data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission privacy:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for privacy.export." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "application-declared" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/privacy", "body": null }, "effects": "Reads privacy data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission privacy:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=privacy.export", "resource": { "kind": "privacy", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/privacy", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.erase", "title": "Erase organization Calendar data", "description": "Permanently erase Calendar-owned rows and avatar objects for the authenticated organization.", "method": "DELETE", "path": "/api/privacy", "permission": "privacy:delete", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false }, "outputSchema": { "type": "object", "title": "Erase organization Calendar data response", "description": "Operation result returned by privacy.erase.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "privacy record", "properties": { "id": { "type": "string", "description": "Stable identifier when the privacy exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=privacy.erase", "resource": { "kind": "privacy", "idPath": "$.id" }, "effects": [ "Permanently removes or invalidates privacy state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission privacy:delete and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "confirmation": "ERASE" }, "expected": "A response matching the published outputSchema for privacy.erase." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/privacy", "body": null }, "effects": "Permanently removes or invalidates privacy state.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission privacy:delete and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=privacy.erase", "resource": { "kind": "privacy", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/privacy", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.protection.canary", "title": "Verify Calendar data protection", "description": "Verify every protected Calendar field is encrypted and readable under the active key ring.", "method": "GET", "path": "/api/privacy/protection/canary", "permission": "privacy:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "outputSchema": { "title": "Verify Calendar data protection response", "description": "Resource response returned by privacy.protection.canary. The service may return the resource directly or in an envelope.", "oneOf": [ { "type": "object", "title": "privacy record", "properties": { "id": { "type": "string", "description": "Stable identifier when the privacy exposes one." } }, "additionalProperties": true }, { "type": "object", "properties": { "data": { "type": "object", "title": "privacy record", "properties": { "id": { "type": "string", "description": "Stable identifier when the privacy exposes one." } }, "additionalProperties": true }, "privacy": { "type": "object", "title": "privacy record", "properties": { "id": { "type": "string", "description": "Stable identifier when the privacy exposes one." } }, "additionalProperties": true } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=privacy.protection.canary", "resource": { "kind": "privacy", "idPath": "$.id" }, "effects": [ "Reads privacy data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission privacy:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for privacy.protection.canary." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "application-declared" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/privacy/protection/canary", "body": null }, "effects": "Reads privacy data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission privacy:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=privacy.protection.canary", "resource": { "kind": "privacy", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/privacy/protection/canary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "Delete workspace", "description": "Delete an empty, non-default Calendar workspace.", "method": "DELETE", "path": "/api/workspaces/{workspaceId}", "permission": "workspace:delete", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Delete workspace response", "description": "Operation result returned by workspaces.delete.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "workspace record", "properties": { "id": { "type": "string", "description": "Stable identifier when the workspace exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=workspaces.delete", "resource": { "kind": "workspace", "idPath": "$.id" }, "effects": [ "Permanently removes or invalidates workspace state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:delete and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "workspaceId": "example" }, "expected": "A response matching the published outputSchema for workspaces.delete." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/workspaces/example", "body": null }, "effects": "Permanently removes or invalidates workspace state.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:delete and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=workspaces.delete", "resource": { "kind": "workspace", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget.get", "title": "Get widget summary", "description": "Get the Calendar widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "host:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "outputSchema": { "title": "Get widget summary response", "description": "Resource response returned by widget.get. The service may return the resource directly or in an envelope.", "oneOf": [ { "type": "object", "title": "widget record", "properties": { "id": { "type": "string", "description": "Stable identifier when the widget exposes one." } }, "additionalProperties": true }, { "type": "object", "properties": { "data": { "type": "object", "title": "widget record", "properties": { "id": { "type": "string", "description": "Stable identifier when the widget exposes one." } }, "additionalProperties": true }, "widget": { "type": "object", "title": "widget record", "properties": { "id": { "type": "string", "description": "Stable identifier when the widget exposes one." } }, "additionalProperties": true } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=widget.get", "resource": { "kind": "widget", "idPath": "$.id" }, "effects": [ "Reads widget data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission host:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for widget.get." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "application-declared" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/widget", "body": null }, "effects": "Reads widget data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission host:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=widget.get", "resource": { "kind": "widget", "idPath": "$.id" }, "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": "host.get", "title": "Get host profile", "description": "Get the selected workspace host profile. A new workspace returns host: null; call host.update once to create its first host before using availability, event types, bookings, or external calendars.", "method": "GET", "path": "/api/admin/me", "permission": "host:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "title": "Get host profile response", "description": "Resource response returned by host.get. The service may return the resource directly or in an envelope.", "oneOf": [ { "type": "object", "title": "host record", "properties": { "id": { "type": "string", "description": "Stable identifier when the host exposes one." } }, "additionalProperties": true }, { "type": "object", "properties": { "data": { "type": "object", "title": "host record", "properties": { "id": { "type": "string", "description": "Stable identifier when the host exposes one." } }, "additionalProperties": true }, "host": { "type": "object", "title": "host record", "properties": { "id": { "type": "string", "description": "Stable identifier when the host exposes one." } }, "additionalProperties": true } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "effects": [ "Reads the selected workspace host profile. A new workspace returns host: null until host.update creates its first host." ], "examples": [ { "input": {}, "expected": "Returns the authenticated context and either the workspace host or host: null." } ], "verify": [ "If host is null, call app_topolo_calendar.host.update before availability, event-type, booking, or external-calendar actions." ], "nextActionIds": [ "app_topolo_calendar.host.update" ], "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=host.get", "resource": { "kind": "host", "idPath": "$.id" }, "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission host:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "application-declared" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/me", "body": null }, "effects": "Reads the selected workspace host profile. A new workspace returns host: null until host.update creates its first host.", "verification": [ "If host is null, call app_topolo_calendar.host.update before availability, event-type, booking, or external-calendar actions." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission host:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=host.get", "resource": { "kind": "host", "idPath": "$.id" }, "next_action_ids": [ "app_topolo_calendar.host.update" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/me", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "host.update", "title": "Create or update host profile", "description": "Create the first host for a new Calendar workspace or update its existing host profile. Calendar generates and preserves the public handle; callers do not provide one.", "method": "PUT", "path": "/api/admin/host", "permission": "host:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "displayName", "timezone" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Create or update host profile response", "description": "Operation result returned by host.update.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "host record", "properties": { "id": { "type": "string", "description": "Stable identifier when the host exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "effects": [ "Creates the first host for a new Calendar workspace, or updates the existing host profile. Calendar generates and preserves the public handle; callers do not supply one." ], "examples": [ { "input": { "displayName": "Northstar Workshops", "timezone": "Asia/Makassar", "avatarUrl": null, "headline": "Hands-on coffee brewing workshops for adventurous teams.", "bio": "Northstar Coffee Roasters hosts practical TrailReady brewing sessions in Bali." }, "expected": "Returns the created or updated host, including its Calendar-generated public handle." } ], "verify": [ "Call app_topolo_calendar.host.get and confirm the returned display name, timezone, profile copy, and generated handle." ], "nextActionIds": [ "app_topolo_calendar.availability.update", "app_topolo_calendar.event_types.create" ], "recovery": { "mode": "irreversible", "instructions": "An existing profile can be restored by calling this action with a prior snapshot. A newly created host has no safe automatic delete action, so confirm the selected workspace before first use." }, "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=host.update", "resource": { "kind": "host", "idPath": "$.id" }, "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission host:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "contractSource": "application-declared" }, "documentation": { "example_input": { "displayName": "Northstar Workshops", "timezone": "Asia/Makassar", "avatarUrl": null, "headline": "Hands-on coffee brewing workshops for adventurous teams.", "bio": "Northstar Coffee Roasters hosts practical TrailReady brewing sessions in Bali." }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/admin/host", "body": { "displayName": "Northstar Workshops", "timezone": "Asia/Makassar", "avatarUrl": null, "headline": "Hands-on coffee brewing workshops for adventurous teams.", "bio": "Northstar Coffee Roasters hosts practical TrailReady brewing sessions in Bali." } }, "effects": "Creates the first host for a new Calendar workspace, or updates the existing host profile. Calendar generates and preserves the public handle; callers do not supply one.", "verification": [ "Call app_topolo_calendar.host.get and confirm the returned display name, timezone, profile copy, and generated handle." ], "recovery": [ { "mode": "irreversible", "instructions": "An existing profile can be restored by calling this action with a prior snapshot. A newly created host has no safe automatic delete action, so confirm the selected workspace before first use." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission host:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=host.update", "resource": { "kind": "host", "idPath": "$.id" }, "next_action_ids": [ "app_topolo_calendar.availability.update", "app_topolo_calendar.event_types.create" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/admin/host", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "event_types.list", "title": "List event types", "description": "List calendar event types.", "method": "GET", "path": "/api/admin/event-types", "permission": "event_types:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "title": "List event types response", "description": "Collection response returned by event_types.list. The service may return the collection directly or in an envelope.", "oneOf": [ { "type": "array", "items": { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true } }, { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true } }, { "type": "object", "additionalProperties": true } ] }, "items": { "type": "array", "items": { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true } }, "event": { "type": "array", "items": { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true } }, "count": { "type": "integer", "minimum": 0 }, "nextCursor": { "type": [ "string", "null" ] } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=event_types.list", "resource": { "kind": "event", "idPath": "$.items[].id" }, "effects": [ "Reads event data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission event_types:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for event_types.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "application-declared" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/event-types", "body": null }, "effects": "Reads event data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission event_types:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=event_types.list", "resource": { "kind": "event", "idPath": "$.items[].id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/event-types", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "event_types.create", "title": "Create event type", "description": "Create a calendar event type.", "method": "POST", "path": "/api/admin/event-types", "permission": "event_types:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "slug": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "bufferBeforeMinutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "bufferAfterMinutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "minNoticeMinutes": { "type": "integer", "minimum": 0, "maximum": 525600 }, "maxAdvanceDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "slotIncrementMinutes": { "type": "integer", "minimum": 5, "maximum": 240 }, "locationKind": { "type": "string", "enum": [ "chat_meeting", "microsoft_teams", "google_meet", "zoom", "in_person", "phone", "custom" ] }, "locationDetail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "slug", "name", "durationMinutes" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Create event type response", "description": "Operation result returned by event_types.create.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=event_types.create", "resource": { "kind": "event", "idPath": "$.id" }, "effects": [ "Changes event state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission event_types:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "slug": "example", "name": "example", "durationMinutes": 5 }, "expected": "A response matching the published outputSchema for event_types.create." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_calendar.event_types.delete", "requiresSnapshot": false, "instructions": "Invoke app_topolo_calendar.event_types.delete with the affected resource identifier after confirming the rollback." }, "rollbackActionId": "app_topolo_calendar.event_types.delete", "contractSource": "application-declared" }, "documentation": { "example_input": { "slug": "example", "name": "example", "durationMinutes": 5 }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/event-types", "body": { "slug": "example", "name": "example", "durationMinutes": 5 } }, "effects": "Changes event state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_calendar.event_types.delete", "requiresSnapshot": false, "instructions": "Invoke app_topolo_calendar.event_types.delete with the affected resource identifier after confirming the rollback." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission event_types:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=event_types.create", "resource": { "kind": "event", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": "app_topolo_calendar.event_types.delete" }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/event-types", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "bookings.list", "title": "List bookings", "description": "List calendar bookings.", "method": "GET", "path": "/api/admin/bookings", "permission": "bookings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "windowStart": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "windowEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "windowStart", "windowEnd" ], "additionalProperties": false }, "target": "api", "outputSchema": { "title": "List bookings response", "description": "Collection response returned by bookings.list. The service may return the collection directly or in an envelope.", "oneOf": [ { "type": "array", "items": { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true } }, { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true } }, { "type": "object", "additionalProperties": true } ] }, "items": { "type": "array", "items": { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true } }, "bookings": { "type": "array", "items": { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true } }, "count": { "type": "integer", "minimum": 0 }, "nextCursor": { "type": [ "string", "null" ] } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "examples": [ { "input": { "windowStart": "2026-08-20T00:00:00+08:00", "windowEnd": "2026-08-21T00:00:00+08:00" }, "expected": "Returns bookings in the selected workspace for 20 August 2026 in the +08:00 timezone window." } ], "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.list", "resource": { "kind": "booking", "idPath": "$.items[].id" }, "effects": [ "Reads booking data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission bookings:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "windowStart": "2026-08-20T00:00:00+08:00", "windowEnd": "2026-08-21T00:00:00+08:00" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/bookings", "body": null }, "effects": "Reads booking data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission bookings:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.list", "resource": { "kind": "booking", "idPath": "$.items[].id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/bookings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "bookings.create", "title": "Create booking", "description": "Create a calendar booking.", "method": "POST", "path": "/api/admin/bookings", "permission": "bookings:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "startAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "endAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "inviteeName": { "type": "string", "minLength": 1 }, "inviteeEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inviteeTimezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inviteeNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "eventTypeId": { "type": "string", "minLength": 1 }, "eventTypeSlug": { "type": "string", "minLength": 1 }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "count": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "until": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "frequency", "interval" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "startAt", "inviteeName" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Create booking response", "description": "Operation result returned by bookings.create.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "examples": [ { "input": { "eventTypeId": "evt_northstar_wholesale_tasting", "startAt": "2026-08-20T10:00:00+08:00", "inviteeName": "Maya Chen", "inviteeEmail": "maya.chen@example.com" }, "expected": "Creates a booking for the selected Northstar event type at 10:00 in the +08:00 timezone." } ], "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.create", "resource": { "kind": "booking", "idPath": "$.id" }, "effects": [ "Changes booking state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission bookings:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "eventTypeId": "evt_northstar_wholesale_tasting", "startAt": "2026-08-20T10:00:00+08:00", "inviteeName": "Maya Chen", "inviteeEmail": "maya.chen@example.com" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/bookings", "body": { "eventTypeId": "evt_northstar_wholesale_tasting", "startAt": "2026-08-20T10:00:00+08:00", "inviteeName": "Maya Chen", "inviteeEmail": "maya.chen@example.com" } }, "effects": "Changes booking state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission bookings:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.create", "resource": { "kind": "booking", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/bookings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "bookings.update", "title": "Update booking", "description": "Update one calendar booking.", "method": "PUT", "path": "/api/admin/bookings/{bookingId}", "permission": "bookings:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bookingId": { "type": "string", "minLength": 1 }, "startAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "endAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "inviteeName": { "type": "string" }, "inviteeEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inviteeTimezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inviteeNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "bookingId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Update booking response", "description": "Operation result returned by bookings.update.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.update", "resource": { "kind": "booking", "idPath": "$.id" }, "effects": [ "Changes booking state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission bookings:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "bookingId": "example" }, "expected": "A response matching the published outputSchema for bookings.update." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_calendar.bookings.update", "requiresSnapshot": true, "instructions": "Capture the current resource before the call, then invoke this action with the captured values to restore it." }, "rollbackActionId": "app_topolo_calendar.bookings.update", "contractSource": "application-declared" }, "documentation": { "example_input": { "bookingId": "example" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/admin/bookings/example", "body": { "bookingId": "example" } }, "effects": "Changes booking state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_calendar.bookings.update", "requiresSnapshot": true, "instructions": "Capture the current resource before the call, then invoke this action with the captured values to restore it." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission bookings:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.update", "resource": { "kind": "booking", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": "app_topolo_calendar.bookings.update" }, "implementation": { "status": "implemented", "route_key": "PUT /api/admin/bookings/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "bookings.cancel", "title": "Cancel booking", "description": "Cancel one calendar booking.", "method": "POST", "path": "/api/admin/bookings/{bookingId}/cancel", "permission": "bookings:write", "readOnly": false, "destructive": true, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bookingId": { "type": "string", "minLength": 1 }, "reason": { "type": "string" } }, "required": [ "bookingId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Cancel booking response", "description": "Operation result returned by bookings.cancel.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.cancel", "resource": { "kind": "booking", "idPath": "$.id" }, "effects": [ "Permanently removes or invalidates booking state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission bookings:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "bookingId": "example" }, "expected": "A response matching the published outputSchema for bookings.cancel." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "bookingId": "example" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/bookings/example/cancel", "body": { "bookingId": "example" } }, "effects": "Permanently removes or invalidates booking state.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission bookings:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.cancel", "resource": { "kind": "booking", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/bookings/*/cancel", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "availability.get", "title": "Get availability", "description": "Get availability rules and overrides for the selected workspace host. If host.get returns host: null, create the host with host.update first.", "method": "GET", "path": "/api/admin/availability", "permission": "availability:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "title": "Get availability response", "description": "Resource response returned by availability.get. The service may return the resource directly or in an envelope.", "oneOf": [ { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true }, { "type": "object", "properties": { "data": { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true }, "availability": { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "effects": [ "Reads weekly availability and date overrides for the selected workspace host." ], "examples": [ { "input": {}, "expected": "Returns rules and overrides for the selected workspace host." } ], "verify": [ "Confirm the response belongs to the host returned by app_topolo_calendar.host.get. If that action returns host: null, create it with app_topolo_calendar.host.update first." ], "nextActionIds": [ "app_topolo_calendar.host.update", "app_topolo_calendar.availability.update" ], "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=availability.get", "resource": { "kind": "availability", "idPath": "$.id" }, "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission availability:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "application-declared" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/availability", "body": null }, "effects": "Reads weekly availability and date overrides for the selected workspace host.", "verification": [ "Confirm the response belongs to the host returned by app_topolo_calendar.host.get. If that action returns host: null, create it with app_topolo_calendar.host.update first." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission availability:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=availability.get", "resource": { "kind": "availability", "idPath": "$.id" }, "next_action_ids": [ "app_topolo_calendar.host.update", "app_topolo_calendar.availability.update" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/availability", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "availability.update", "title": "Update availability", "description": "Update availability rules.", "method": "PUT", "path": "/api/admin/availability", "permission": "availability:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "integer", "minimum": 0, "maximum": 6 }, "startMinute": { "type": "integer", "minimum": 0, "maximum": 1439 }, "endMinute": { "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "dayOfWeek", "startMinute", "endMinute" ], "additionalProperties": false } } }, "required": [ "rules" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Update availability response", "description": "Operation result returned by availability.update.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=availability.update", "resource": { "kind": "availability", "idPath": "$.id" }, "effects": [ "Changes availability state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission availability:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "rules": [] }, "expected": "A response matching the published outputSchema for availability.update." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_calendar.availability.update", "requiresSnapshot": true, "instructions": "Capture the current resource before the call, then invoke this action with the captured values to restore it." }, "rollbackActionId": "app_topolo_calendar.availability.update", "contractSource": "application-declared" }, "documentation": { "example_input": { "rules": [] }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/admin/availability", "body": { "rules": [] } }, "effects": "Changes availability state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_calendar.availability.update", "requiresSnapshot": true, "instructions": "Capture the current resource before the call, then invoke this action with the captured values to restore it." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission availability:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=availability.update", "resource": { "kind": "availability", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": "app_topolo_calendar.availability.update" }, "implementation": { "status": "implemented", "route_key": "PUT /api/admin/availability", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "external_calendars.list", "title": "List external calendars", "description": "List connected external calendars.", "method": "GET", "path": "/api/admin/external-calendars", "permission": "availability:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "title": "List external calendars response", "description": "Collection response returned by external_calendars.list. The service may return the collection directly or in an envelope.", "oneOf": [ { "type": "array", "items": { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true } }, { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true } }, { "type": "object", "additionalProperties": true } ] }, "items": { "type": "array", "items": { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true } }, "external": { "type": "array", "items": { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true } }, "count": { "type": "integer", "minimum": 0 }, "nextCursor": { "type": [ "string", "null" ] } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=external_calendars.list", "resource": { "kind": "external", "idPath": "$.items[].id" }, "effects": [ "Reads external data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission availability:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for external_calendars.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "application-declared" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/external-calendars", "body": null }, "effects": "Reads external data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission availability:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=external_calendars.list", "resource": { "kind": "external", "idPath": "$.items[].id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/external-calendars", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "external_calendars.sync", "title": "Sync external calendar", "description": "Sync an external calendar connection.", "method": "POST", "path": "/api/admin/external-calendars/{calendarId}/sync", "permission": "availability:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "calendarId": { "type": "string", "minLength": 1 }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "startAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "endAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "sourceUid": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "busyType": { "type": "string", "enum": [ "busy", "tentative", "out_of_office", "unknown" ] } }, "required": [ "startAt", "endAt" ], "additionalProperties": false } }, "nextSyncCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "windowStart": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "windowEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "calendarId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Sync external calendar response", "description": "Operation result returned by external_calendars.sync.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=external_calendars.sync", "resource": { "kind": "external", "idPath": "$.id" }, "effects": [ "Changes external state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission availability:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "calendarId": "example" }, "expected": "A response matching the published outputSchema for external_calendars.sync." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "calendarId": "example" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/external-calendars/example/sync", "body": { "calendarId": "example" } }, "effects": "Changes external state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission availability:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=external_calendars.sync", "resource": { "kind": "external", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/external-calendars/*/sync", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "host.avatar.upload", "title": "Upload host avatar", "description": "Upload the authenticated host's avatar.", "method": "POST", "path": "/api/admin/host/avatar", "permission": "host:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentBase64": { "type": "string", "minLength": 1 }, "contentType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "image/gif" ] }, "fileName": { "type": "string", "minLength": 1 } }, "required": [ "contentBase64", "contentType", "fileName" ], "additionalProperties": false }, "agentContract": { "upload": { "profile": "inline-base64", "contentField": "contentBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 2097152, "acceptedContentTypes": [ "image/jpeg", "image/png", "image/webp", "image/gif" ] }, "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=host.avatar.upload", "resource": { "kind": "host", "idPath": "$.id" }, "effects": [ "Changes host state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission host:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "contentBase64": "Sample content base64", "contentType": "image/jpeg", "fileName": "Sample file name" }, "expected": "A successful response conforming to outputSchema; re-read the affected host to verify the intended change." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "application-declared" }, "target": "api", "outputSchema": { "type": "object", "title": "Upload host avatar response", "description": "Operation result returned by host.avatar.upload.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "host record", "properties": { "id": { "type": "string", "description": "Stable identifier when the host exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "contentBase64": "Sample content base64", "contentType": "image/jpeg", "fileName": "Sample file name" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/host/avatar", "body": { "contentBase64": "Sample content base64", "contentType": "image/jpeg", "fileName": "Sample file name" } }, "effects": "Changes host state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission host:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=host.avatar.upload", "resource": { "kind": "host", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/host/avatar", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "event_types.get", "title": "Get event type", "description": "Get a Calendar event type.", "method": "GET", "path": "/api/admin/event-types/{eventTypeId}", "permission": "event_types:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventTypeId": { "type": "string", "minLength": 1 } }, "required": [ "eventTypeId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "title": "Get event type response", "description": "Resource response returned by event_types.get. The service may return the resource directly or in an envelope.", "oneOf": [ { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true }, { "type": "object", "properties": { "data": { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true }, "event": { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=event_types.get", "resource": { "kind": "event", "idPath": "$.id" }, "effects": [ "Reads event data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission event_types:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": { "eventTypeId": "example" }, "expected": "A response matching the published outputSchema for event_types.get." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "eventTypeId": "example" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/event-types/example", "body": null }, "effects": "Reads event data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission event_types:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=event_types.get", "resource": { "kind": "event", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/event-types/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "event_types.update", "title": "Update event type", "description": "Update a Calendar event type.", "method": "PUT", "path": "/api/admin/event-types/{eventTypeId}", "permission": "event_types:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventTypeId": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "bufferBeforeMinutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "bufferAfterMinutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "minNoticeMinutes": { "type": "integer", "minimum": 0, "maximum": 525600 }, "maxAdvanceDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "slotIncrementMinutes": { "type": "integer", "minimum": 5, "maximum": 240 }, "locationKind": { "type": "string", "enum": [ "chat_meeting", "microsoft_teams", "google_meet", "zoom", "in_person", "phone", "custom" ] }, "locationDetail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayOrder": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "isActive": { "type": "boolean" }, "approvalRequired": { "type": "boolean" } }, "required": [ "eventTypeId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Update event type response", "description": "Operation result returned by event_types.update.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=event_types.update", "resource": { "kind": "event", "idPath": "$.id" }, "effects": [ "Changes event state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission event_types:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "eventTypeId": "example" }, "expected": "A response matching the published outputSchema for event_types.update." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_calendar.event_types.update", "requiresSnapshot": true, "instructions": "Capture the current resource before the call, then invoke this action with the captured values to restore it." }, "rollbackActionId": "app_topolo_calendar.event_types.update", "contractSource": "application-declared" }, "documentation": { "example_input": { "eventTypeId": "example" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/admin/event-types/example", "body": { "eventTypeId": "example" } }, "effects": "Changes event state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_calendar.event_types.update", "requiresSnapshot": true, "instructions": "Capture the current resource before the call, then invoke this action with the captured values to restore it." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission event_types:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=event_types.update", "resource": { "kind": "event", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": "app_topolo_calendar.event_types.update" }, "implementation": { "status": "implemented", "route_key": "PUT /api/admin/event-types/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "event_types.delete", "title": "Delete event type", "description": "Delete an unused Calendar event type.", "method": "DELETE", "path": "/api/admin/event-types/{eventTypeId}", "permission": "event_types:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventTypeId": { "type": "string", "minLength": 1 } }, "required": [ "eventTypeId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Delete event type response", "description": "Operation result returned by event_types.delete.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=event_types.delete", "resource": { "kind": "event", "idPath": "$.id" }, "effects": [ "Permanently removes or invalidates event state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission event_types:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "eventTypeId": "example" }, "expected": "A response matching the published outputSchema for event_types.delete." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "eventTypeId": "example" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/admin/event-types/example", "body": null }, "effects": "Permanently removes or invalidates event state.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission event_types:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=event_types.delete", "resource": { "kind": "event", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/admin/event-types/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "availability.overrides.list", "title": "List availability overrides", "description": "List host date-specific availability overrides.", "method": "GET", "path": "/api/admin/availability/overrides", "permission": "availability:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "title": "List availability overrides response", "description": "Collection response returned by availability.overrides.list. The service may return the collection directly or in an envelope.", "oneOf": [ { "type": "array", "items": { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true } }, { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true } }, { "type": "object", "additionalProperties": true } ] }, "items": { "type": "array", "items": { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true } }, "availability": { "type": "array", "items": { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true } }, "count": { "type": "integer", "minimum": 0 }, "nextCursor": { "type": [ "string", "null" ] } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=availability.overrides.list", "resource": { "kind": "availability", "idPath": "$.items[].id" }, "effects": [ "Reads availability data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission availability:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for availability.overrides.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "application-declared" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/availability/overrides", "body": null }, "effects": "Reads availability data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission availability:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=availability.overrides.list", "resource": { "kind": "availability", "idPath": "$.items[].id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/availability/overrides", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "availability.overrides.create", "title": "Create availability override", "description": "Create or replace a host date-specific availability override.", "method": "POST", "path": "/api/admin/availability/overrides", "permission": "availability:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "startMinute": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1439 }, { "type": "null" } ] }, "endMinute": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1440 }, { "type": "null" } ] } }, "required": [ "date" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Create availability override response", "description": "Operation result returned by availability.overrides.create.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "examples": [ { "input": { "date": "2026-08-20", "startMinute": null, "endMinute": null }, "expected": "Creates a closed-day override for 20 August 2026 in the selected workspace host timezone." } ], "verify": [ "Call app_topolo_calendar.availability.overrides.list and confirm the returned date and minute bounds." ], "nextActionIds": [ "app_topolo_calendar.availability.overrides.list" ], "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=availability.overrides.create", "resource": { "kind": "availability", "idPath": "$.id" }, "effects": [ "Changes availability state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission availability:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_calendar.availability.overrides.delete", "requiresSnapshot": false, "instructions": "Invoke app_topolo_calendar.availability.overrides.delete with the affected resource identifier after confirming the rollback." }, "rollbackActionId": "app_topolo_calendar.availability.overrides.delete", "contractSource": "application-declared" }, "documentation": { "example_input": { "date": "2026-08-20", "startMinute": null, "endMinute": null }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/availability/overrides", "body": { "date": "2026-08-20", "startMinute": null, "endMinute": null } }, "effects": "Changes availability state in the selected Topolo resource context.", "verification": [ "Call app_topolo_calendar.availability.overrides.list and confirm the returned date and minute bounds." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_calendar.availability.overrides.delete", "requiresSnapshot": false, "instructions": "Invoke app_topolo_calendar.availability.overrides.delete with the affected resource identifier after confirming the rollback." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission availability:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=availability.overrides.create", "resource": { "kind": "availability", "idPath": "$.id" }, "next_action_ids": [ "app_topolo_calendar.availability.overrides.list" ], "rollback_action_id": "app_topolo_calendar.availability.overrides.delete" }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/availability/overrides", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "availability.overrides.delete", "title": "Delete availability override", "description": "Delete a host date-specific availability override.", "method": "DELETE", "path": "/api/admin/availability/overrides/{overrideId}", "permission": "availability:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "overrideId": { "type": "string", "minLength": 1 } }, "required": [ "overrideId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Delete availability override response", "description": "Operation result returned by availability.overrides.delete.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=availability.overrides.delete", "resource": { "kind": "availability", "idPath": "$.id" }, "effects": [ "Permanently removes or invalidates availability state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission availability:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "overrideId": "example" }, "expected": "A response matching the published outputSchema for availability.overrides.delete." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "overrideId": "example" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/admin/availability/overrides/example", "body": null }, "effects": "Permanently removes or invalidates availability state.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission availability:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=availability.overrides.delete", "resource": { "kind": "availability", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/admin/availability/overrides/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "bookings.get", "title": "Get booking", "description": "Get a Calendar booking and delivery details.", "method": "GET", "path": "/api/admin/bookings/{bookingId}", "permission": "bookings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bookingId": { "type": "string", "minLength": 1 } }, "required": [ "bookingId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "title": "Get booking response", "description": "Resource response returned by bookings.get. The service may return the resource directly or in an envelope.", "oneOf": [ { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, { "type": "object", "properties": { "data": { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, "booking": { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.get", "resource": { "kind": "booking", "idPath": "$.id" }, "effects": [ "Reads booking data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission bookings:read and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "examples": [ { "input": { "bookingId": "example" }, "expected": "A response matching the published outputSchema for bookings.get." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "bookingId": "example" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/bookings/example", "body": null }, "effects": "Reads booking data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected resource context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission bookings:read and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.get", "resource": { "kind": "booking", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/bookings/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "bookings.approve", "title": "Approve booking", "description": "Approve a pending Calendar booking.", "method": "POST", "path": "/api/admin/bookings/{bookingId}/approve", "permission": "bookings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bookingId": { "type": "string", "minLength": 1 } }, "required": [ "bookingId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Approve booking response", "description": "Operation result returned by bookings.approve.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.approve", "resource": { "kind": "booking", "idPath": "$.id" }, "effects": [ "Changes booking state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission bookings:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "bookingId": "example" }, "expected": "A response matching the published outputSchema for bookings.approve." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "bookingId": "example" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/bookings/example/approve", "body": { "bookingId": "example" } }, "effects": "Changes booking state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission bookings:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.approve", "resource": { "kind": "booking", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/bookings/*/approve", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "bookings.reschedule", "title": "Reschedule booking", "description": "Reschedule a Calendar booking.", "method": "POST", "path": "/api/admin/bookings/{bookingId}/reschedule", "permission": "bookings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bookingId": { "type": "string", "minLength": 1 }, "startAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "endAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "inviteeName": { "type": "string" }, "inviteeEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inviteeTimezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inviteeNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "bookingId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Reschedule booking response", "description": "Operation result returned by bookings.reschedule.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.reschedule", "resource": { "kind": "booking", "idPath": "$.id" }, "effects": [ "Changes booking state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission bookings:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "bookingId": "example" }, "expected": "A response matching the published outputSchema for bookings.reschedule." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "bookingId": "example" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/bookings/example/reschedule", "body": { "bookingId": "example" } }, "effects": "Changes booking state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission bookings:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.reschedule", "resource": { "kind": "booking", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/bookings/*/reschedule", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "bookings.invite.resend", "title": "Resend booking invite", "description": "Resend the current booking invitation or cancellation notice.", "method": "POST", "path": "/api/admin/bookings/{bookingId}/resend-invite", "permission": "bookings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bookingId": { "type": "string", "minLength": 1 } }, "required": [ "bookingId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Resend booking invite response", "description": "Operation result returned by bookings.invite.resend.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.invite.resend", "resource": { "kind": "booking", "idPath": "$.id" }, "effects": [ "Changes booking state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission bookings:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "bookingId": "example" }, "expected": "A response matching the published outputSchema for bookings.invite.resend." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "bookingId": "example" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/bookings/example/resend-invite", "body": { "bookingId": "example" } }, "effects": "Changes booking state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission bookings:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=bookings.invite.resend", "resource": { "kind": "booking", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/bookings/*/resend-invite", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "external_calendars.create", "title": "Create external calendar", "description": "Connect an ICS or manually synchronized external calendar.", "method": "POST", "path": "/api/admin/external-calendars", "permission": "availability:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "provider": { "type": "string", "enum": [ "ics", "manual" ] }, "accountEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "accountEmail" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Create external calendar response", "description": "Operation result returned by external_calendars.create.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=external_calendars.create", "resource": { "kind": "external", "idPath": "$.id" }, "effects": [ "Changes external state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission availability:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "accountEmail": "agent@example.com" }, "expected": "A response matching the published outputSchema for external_calendars.create." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_calendar.external_calendars.delete", "requiresSnapshot": false, "instructions": "Invoke app_topolo_calendar.external_calendars.delete with the affected resource identifier after confirming the rollback." }, "rollbackActionId": "app_topolo_calendar.external_calendars.delete", "contractSource": "application-declared" }, "documentation": { "example_input": { "accountEmail": "agent@example.com" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/external-calendars", "body": { "accountEmail": "agent@example.com" } }, "effects": "Changes external state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_calendar.external_calendars.delete", "requiresSnapshot": false, "instructions": "Invoke app_topolo_calendar.external_calendars.delete with the affected resource identifier after confirming the rollback." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission availability:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=external_calendars.create", "resource": { "kind": "external", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": "app_topolo_calendar.external_calendars.delete" }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/external-calendars", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "external_calendars.caldav.create", "title": "Connect CalDAV calendar", "description": "Connect a CalDAV external calendar.", "method": "POST", "path": "/api/admin/external-calendars/caldav", "permission": "availability:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "accountEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "calendarUrl": { "type": "string", "format": "uri" }, "username": { "type": "string", "minLength": 1 }, "password": { "type": "string", "minLength": 1 } }, "required": [ "accountEmail", "calendarUrl", "username", "password" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Connect CalDAV calendar response", "description": "Operation result returned by external_calendars.caldav.create.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=external_calendars.caldav.create", "resource": { "kind": "external", "idPath": "$.id" }, "effects": [ "Changes external state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission availability:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "accountEmail": "agent@example.com", "calendarUrl": "https://example.com", "username": "example", "password": "example" }, "expected": "A response matching the published outputSchema for external_calendars.caldav.create." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "accountEmail": "agent@example.com", "calendarUrl": "https://example.com", "username": "example", "password": "example" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/external-calendars/caldav", "body": { "accountEmail": "agent@example.com", "calendarUrl": "https://example.com", "username": "example", "password": "example" } }, "effects": "Changes external state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission availability:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=external_calendars.caldav.create", "resource": { "kind": "external", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/external-calendars/caldav", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "external_calendars.oauth.start", "title": "Start calendar OAuth", "description": "Start an interactive Google or Microsoft calendar connection.", "method": "POST", "path": "/api/admin/external-calendars/oauth/start", "permission": "availability:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "provider": { "type": "string", "enum": [ "google", "microsoft" ] }, "redirectPath": { "type": "string" } }, "required": [ "provider" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Start calendar OAuth response", "description": "Operation result returned by external_calendars.oauth.start.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=external_calendars.oauth.start", "resource": { "kind": "external", "idPath": "$.id" }, "effects": [ "Changes external state in the selected Topolo resource context." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission availability:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "provider": "google" }, "expected": "A response matching the published outputSchema for external_calendars.oauth.start." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "provider": "google" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/external-calendars/oauth/start", "body": { "provider": "google" } }, "effects": "Changes external state in the selected Topolo resource context.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission availability:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=external_calendars.oauth.start", "resource": { "kind": "external", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/external-calendars/oauth/start", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "external_calendars.delete", "title": "Delete external calendar", "description": "Disconnect an external calendar.", "method": "DELETE", "path": "/api/admin/external-calendars/{calendarId}", "permission": "availability:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "calendarId": { "type": "string", "minLength": 1 } }, "required": [ "calendarId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "title": "Delete external calendar response", "description": "Operation result returned by external_calendars.delete.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=external_calendars.delete", "resource": { "kind": "external", "idPath": "$.id" }, "effects": [ "Permanently removes or invalidates external state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission availability:write and the required resource binding." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." }, { "status": 409, "code": "state_conflict", "recovery": "Read the current resource state, reconcile the intended change, and retry only if still valid." } ], "verify": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "examples": [ { "input": { "calendarId": "example" }, "expected": "A response matching the published outputSchema for external_calendars.delete." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "application-declared" }, "documentation": { "example_input": { "calendarId": "example" }, "cli_example": [ "topolo actions --service topolo-calendar --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/admin/external-calendars/example", "body": null }, "effects": "Permanently removes or invalidates external state.", "verification": [ "Validate the response against outputSchema and re-read the affected resource to confirm the intended state." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission availability:write and the required resource binding.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID.", "409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-calendar&action=external_calendars.delete", "resource": { "kind": "external", "idPath": "$.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/admin/external-calendars/*", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 51, "matched_actions": 32, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 19, "configured_exclusions": 17, "configuration_findings": [], "notes": [ "24 manually-declared route(s)" ] }, "runtime_contract_audit": { "status": "verified", "actions": 32, "contracts": 32, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/index.ts" ], "authorization_sources": [ "apps/api/src/index.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloCalendar/topolo.mobile-experience.json", "contract": { "version": "2026-06-27", "status": "approved", "mode": "native_capability", "appId": "app_topolo_calendar", "localizationNamespace": "calendar", "permissions": [ "bookings:read", "bookings:write" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/agenda", "auth": { "audience": "topolo-calendar", "scopes": [ "bookings:read", "bookings:write" ] }, "routes": [ { "path": "/agenda", "apiPath": "/api/admin/bookings", "title": "Agenda", "titleKey": "calendar.mobile.routes.agenda.title", "template": "calendar.agenda", "dataSource": "calendar.agenda.list", "detailRoute": "/agenda/:id", "actions": [ { "id": "calendar.bookings.create", "title": "Create booking", "type": "record.create", "permission": "bookings:write", "method": "POST", "path": "/api/admin/bookings", "fields": [ { "key": "startAt", "label": "Start", "type": "datetime", "required": true }, { "key": "durationMinutes", "label": "Duration minutes", "type": "number", "required": true }, { "key": "inviteeName", "label": "Invitee name", "type": "text", "required": true }, { "key": "inviteeEmail", "label": "Invitee email", "type": "email" }, { "key": "inviteeNotes", "label": "Notes", "labelKey": "calendar.bookingNew.notes", "type": "textarea" } ], "titleKey": "calendar.mobile.actions.bookings.create.title" }, { "id": "calendar.bookings.update", "title": "Update booking", "type": "record.update", "permission": "bookings:write", "method": "PUT", "path": "/api/admin/bookings/:id", "fields": [ { "key": "startAt", "label": "Start", "type": "datetime" }, { "key": "durationMinutes", "label": "Duration minutes", "type": "number" }, { "key": "inviteeName", "label": "Invitee name", "type": "text" }, { "key": "inviteeEmail", "label": "Invitee email", "type": "email" }, { "key": "inviteeNotes", "label": "Notes", "labelKey": "calendar.bookingEdit.notes", "type": "textarea" } ], "titleKey": "calendar.mobile.actions.bookings.update.title" } ] }, { "path": "/agenda/:id", "apiPath": "/api/admin/bookings/:id", "title": "Booking", "titleKey": "calendar.mobile.routes.bookingDetail.title", "template": "record.detail", "dataSource": "calendar.agenda.detail" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "ALL", "path": "*", "source_path": "apps/TopoloCalendar/apps/api/src/index.ts" } ], "ui_routes": [ { "path": "/app", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/app/dashboard", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/app/calendar", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/app/event-types", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/app/availability", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/app/availability/:section", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/app/settings", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/app/settings/:section", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/app/getting-started", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/calendar", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/event-types", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/availability", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/settings", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/manage/:token", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/embed/:handle", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/embed/:handle/:slug", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/widget/:handle", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/widget/:handle/:slug", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/:handle", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" }, { "path": "/:handle/:slug", "source_path": "apps/TopoloCalendar/apps/web/src/client/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "internal/apps/calendar", "applications/calendar" ], "present_paths": [ "internal/apps/calendar", "applications/calendar" ], "missing_paths": [], "human_reference": "/systems/topolo-calendar", "machine_reference": "/machine/systems/topolo-calendar.json", "action_examples": 32, "action_schemas": 32 }, "source_findings": [] }, "topolo-chat": { "id": "topolo-chat", "name": "Chat", "slug": "topolo-chat", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloChat" ], "source_revisions": [ { "source_path": "apps/TopoloChat", "repository": "apps/TopoloChat", "revision": "9b3181a11595534171029d26d81de7134dcc4b9b", "ref": "origin/staging" } ], "source_counts": { "source_files": 150, "test_files": 76, "test_cases": 0, "migration_files": 0, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 101, "mobile_contracts": 1, "notifications": 6, "package_manifests": 2, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloChat/topolo.app.json", "service_slug": "topolo-chat", "name": "topolo-chat", "app_id": "app_topolo_chat", "compatibility_date": "2026-05-01", "primary_target": "web", "environments": [ "development", "production", "staging" ], "targets": [ { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/index.ts", "worker_name": "topolo-chat-api", "subdomain": null, "healthcheck_path": "/healthz", "variable_names": [ "CHAT_AUDIT_RETENTION_DAYS", "CHAT_MESSAGE_RETENTION_DAYS", "CHAT_OPERATIONAL_RETENTION_DAYS", "CHAT_PUBLIC_BASE_URL", "CLOUDFLARE_ACCOUNT_ID", "ENVIRONMENT", "REALTIMEKIT_APP_ID", "REALTIMEKIT_HOST_PRESET", "REALTIMEKIT_PARTICIPANT_PRESET", "TOPOLO_AGENT_URL", "TOPOLO_AUTH_BASE_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "CHAT_CORE_DB", "target": null }, { "kind": "d1", "binding": "CHAT_MESSAGES_DB", "target": null }, { "kind": "d1", "binding": "CHAT_MEETINGS_DB", "target": null }, { "kind": "d1", "binding": "CHAT_AGENT_DB", "target": null }, { "kind": "r2", "binding": "CHAT_UPLOADS", "target": null }, { "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 }, { "kind": "durableObjects", "binding": "WORKSPACE_REALTIME", "target": null }, { "kind": "durableObjects", "binding": "MEETING_ROOM", "target": null }, { "kind": "durableObjects", "binding": "REMOTE_ASSIST", "target": null } ] }, { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/index.ts", "worker_name": "topolo-chat", "subdomain": "chat", "healthcheck_path": "/healthz", "variable_names": [ "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null } ] } ], "notifications": [ "chat.call.missed", "chat.call.started", "chat.dm.message_received", "chat.meeting.reminder_due", "chat.mention.created", "chat.remote_assist.requested" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_chat", "events": [ { "type": "chat.call.missed", "version": 1, "description": "A direct audio or video call ended without being answered.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string" }, "category": { "type": "string" }, "severity": { "enum": [ "info", "success", "warning", "critical" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "Missed video call", "body": "Ada Caller called you in Chat.", "object_id": "meet_123", "occurred_at": "2026-07-19T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^chat:call:missed:" }, "sensitiveFields": [] }, { "type": "chat.call.started", "version": 1, "description": "A direct audio or video call started.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "thread_key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "A direct audio or video call started.", "body": "Open the owning app to review this event.", "object_id": "object_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^chat:call:" }, "sensitiveFields": [] }, { "type": "chat.dm.message_received", "version": 1, "description": "A direct message was received.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "thread_key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "A direct message was received.", "body": "Open the owning app to review this event.", "object_id": "object_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^chat:dm:" }, "sensitiveFields": [] }, { "type": "chat.meeting.reminder_due", "version": 1, "description": "A scheduled Chat meeting reached its configured reminder time.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string" }, "category": { "type": "string" }, "severity": { "enum": [ "info", "success", "warning", "critical" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "Meeting starts in 10 minutes", "body": "Weekly planning", "object_id": "meet_123", "occurred_at": "2026-07-19T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^chat:meeting-reminder:" }, "sensitiveFields": [] }, { "type": "chat.mention.created", "version": 1, "description": "A persisted channel message mentioned an organization member.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string" }, "category": { "type": "string" }, "severity": { "enum": [ "info", "success", "warning", "critical" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "title": "Ada mentioned you", "body": "@Grace can you review this?", "object_id": "msg_123", "occurred_at": "2026-07-19T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^chat:mention:" }, "sensitiveFields": [] }, { "type": "chat.remote_assist.requested", "version": 1, "description": "A participant requested remote assist from a meeting host.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string" }, "category": { "type": "string" }, "severity": { "enum": [ "info", "success", "warning", "critical" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "Remote assist requested", "body": "Ada requested remote assist during a meeting.", "object_id": "assist_123", "occurred_at": "2026-07-19T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^chat:remote-assist:" }, "sensitiveFields": [] } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "workspace:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "declared_unserved", "route_key": "GET /api/widget", "evidence": "No matching served route was extracted from canonical staging source." } }, { "name": "widget_chat.bootstrap", "title": "Get cross-app Chat widget bootstrap", "description": "Get contacts, recent conversations, unread totals, and realtime metadata for the cross-app Chat widget.", "method": "GET", "path": "/api/widget/chat", "permission": "direct_messages:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/widget/chat", "body": null }, "effects": "Reads state through GET /api/widget/chat without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/widget/chat", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget_chat.update_workspace_attention", "title": "Update Chat widget attention", "description": "Set the current user attention level and optional snooze time for one resolved Chat workspace.", "method": "PATCH", "path": "/api/widget/workspaces/{workspaceId}/attention", "permission": "workspace:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "attentionLevel": { "type": "string", "enum": [ "all", "mentions", "none" ] }, "snoozedUntil": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "workspaceId", "attentionLevel" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceId": "example", "attentionLevel": "all" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/widget/workspaces/example/attention", "body": { "workspaceId": "example", "attentionLevel": "all" } }, "effects": "May change state through PATCH /api/widget/workspaces/{workspaceId}/attention. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/widget/workspaces/*/attention", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget_chat.open_dm", "title": "Open cross-app Chat conversation", "description": "Create or open a human direct message conversation for the cross-app Chat widget.", "method": "POST", "path": "/api/widget/dms", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "memberId": { "type": "string" }, "type": { "type": "string", "const": "human" } }, "required": [ "memberId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "memberId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/widget/dms", "body": { "memberId": "example" } }, "effects": "May change state through POST /api/widget/dms. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/widget/dms", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget_chat.list_messages", "title": "List cross-app Chat messages", "description": "List normalized human direct-message messages for the cross-app Chat widget.", "method": "GET", "path": "/api/widget/dms/{conversationId}/messages", "permission": "direct_messages:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "before": { "type": "string" } }, "required": [ "conversationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List cross-app Chat messages.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/widget/dms/example/messages", "body": null }, "effects": "Reads state through GET /api/widget/dms/{conversationId}/messages without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/widget/dms/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget_chat.list_channel_messages", "title": "List cross-app Chat channel messages", "description": "List normalized channel messages for the cross-app Chat widget.", "method": "GET", "path": "/api/widget/channels/{channelId}/messages", "permission": "messages:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "before": { "type": "string" } }, "required": [ "channelId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List cross-app Chat channel messages.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/widget/channels/example/messages", "body": null }, "effects": "Reads state through GET /api/widget/channels/{channelId}/messages without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/widget/channels/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget_chat.send_dm_message", "title": "Send cross-app Chat direct message", "description": "Send a human direct-message turn from the cross-app Chat widget.", "method": "POST", "path": "/api/widget/dms/{conversationId}/messages", "permission": "direct_messages:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "threadParentId": { "type": "string", "minLength": 1 }, "thread_parent_id": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "body" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Send cross-app Chat direct message.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example", "body": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/widget/dms/example/messages", "body": { "conversationId": "example", "body": "example" } }, "effects": "May change state through POST /api/widget/dms/{conversationId}/messages. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/widget/dms/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget_chat.send_channel_message", "title": "Send cross-app Chat channel message", "description": "Send a channel message turn from the cross-app Chat widget.", "method": "POST", "path": "/api/widget/channels/{channelId}/messages", "permission": "messages:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "threadParentId": { "type": "string", "minLength": 1 }, "thread_parent_id": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "body" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Send cross-app Chat channel message.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example", "body": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/widget/channels/example/messages", "body": { "channelId": "example", "body": "example" } }, "effects": "May change state through POST /api/widget/channels/{channelId}/messages. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/widget/channels/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget_chat.request_upload", "title": "Request cross-app Chat upload", "description": "Create a compact upload draft for an image, file, or voice note sent from the cross-app Chat widget.", "method": "POST", "path": "/api/widget/uploads/request", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1 }, "contentType": { "type": "string", "minLength": 1 }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 26214400 } }, "required": [ "fileName", "contentType", "sizeBytes" ], "additionalProperties": false }, "agentContract": { "upload": { "profile": "url-session", "fileNameField": "fileName", "contentTypeField": "contentType", "sizeField": "sizeBytes", "maxBytes": 26214400, "acceptedContentTypes": [ "*/*" ], "uploadUrlPath": "upload.uploadUrl", "uploadMethod": "PUT" } }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "fileName": "example", "contentType": "example", "sizeBytes": 1 }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/widget/uploads/request", "body": { "fileName": "example", "contentType": "example", "sizeBytes": 1 } }, "effects": "May change state through POST /api/widget/uploads/request. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/widget/uploads/request", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget_chat.upload_content", "title": "Upload cross-app Chat file content", "description": "Upload bytes for a compact widget upload draft.", "method": "PUT", "path": "/api/widget/uploads/{uploadId}/content", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "uploadId": { "type": "string", "minLength": 1 } }, "required": [ "uploadId" ], "additionalProperties": {} }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Upload cross-app Chat file content.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "uploadId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/widget/uploads/example/content", "body": { "uploadId": "example" } }, "effects": "May change state through PUT /api/widget/uploads/{uploadId}/content. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/widget/uploads/*/content", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget_chat.complete_upload", "title": "Complete cross-app Chat upload", "description": "Attach an uploaded image, file, or voice note to a human direct message from the cross-app Chat widget.", "method": "POST", "path": "/api/widget/dms/{conversationId}/uploads/complete", "permission": "direct_messages:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "uploadId": { "type": "string", "minLength": 1 }, "uploadIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "messageBody": { "type": "string" }, "threadParentId": { "type": "string", "minLength": 1 }, "thread_parent_id": { "type": "string", "minLength": 1 } }, "required": [ "conversationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Complete cross-app Chat upload.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/widget/dms/example/uploads/complete", "body": { "conversationId": "example" } }, "effects": "May change state through POST /api/widget/dms/{conversationId}/uploads/complete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/widget/dms/*/uploads/complete", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget_chat.complete_channel_upload", "title": "Complete cross-app Chat channel upload", "description": "Attach an uploaded image, file, or voice note to a channel message from the cross-app Chat widget.", "method": "POST", "path": "/api/widget/channels/{channelId}/uploads/complete", "permission": "messages:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "uploadId": { "type": "string", "minLength": 1 }, "uploadIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "messageBody": { "type": "string" }, "threadParentId": { "type": "string", "minLength": 1 }, "thread_parent_id": { "type": "string", "minLength": 1 } }, "required": [ "channelId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Complete cross-app Chat channel upload.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/widget/channels/example/uploads/complete", "body": { "channelId": "example" } }, "effects": "May change state through POST /api/widget/channels/{channelId}/uploads/complete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/widget/channels/*/uploads/complete", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget_chat.start_call", "title": "Start cross-app Chat call", "description": "Start a voice or video call for a human direct-message conversation from the cross-app Chat widget.", "method": "POST", "path": "/api/widget/dms/{conversationId}/calls", "permission": "direct_messages:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "audio", "video" ] } }, "required": [ "conversationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Start cross-app Chat call.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/widget/dms/example/calls", "body": { "conversationId": "example" } }, "effects": "May change state through POST /api/widget/dms/{conversationId}/calls. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/widget/dms/*/calls", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget_chat.mark_read", "title": "Mark cross-app Chat conversation read", "description": "Mark a cross-app Chat human direct-message conversation read.", "method": "POST", "path": "/api/widget/dms/{conversationId}/read", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Mark cross-app Chat conversation read.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/widget/dms/example/read", "body": { "conversationId": "example" } }, "effects": "May change state through POST /api/widget/dms/{conversationId}/read. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/widget/dms/*/read", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget_chat.mark_channel_read", "title": "Mark cross-app Chat channel read", "description": "Mark a cross-app Chat channel conversation read.", "method": "POST", "path": "/api/widget/channels/{channelId}/read", "permission": "messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 } }, "required": [ "channelId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Mark cross-app Chat channel read.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/widget/channels/example/read", "body": { "channelId": "example" } }, "effects": "May change state through POST /api/widget/channels/{channelId}/read. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/widget/channels/*/read", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspace.bootstrap", "title": "Get workspace bootstrap", "description": "Get the signed workspace bootstrap payload for this service.", "method": "GET", "path": "/api/bootstrap", "permission": "workspace:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "privacy.export", "title": "Export workspace data", "description": "Export the verified workspace's Chat records and protected object inventory.", "method": "GET", "path": "/api/privacy/export", "permission": "workspace:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/privacy/export", "body": null }, "effects": "Reads state through GET /api/privacy/export without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/privacy/export", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.protection_canary", "title": "Inspect workspace data protection", "description": "Inspect the verified workspace for remaining unprotected Chat fields and objects. Platform super administrators may name a legacy workspace directly.", "method": "GET", "path": "/api/privacy/protection/canary", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "targetWorkspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "targetWorkspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/privacy/protection/canary", "body": null }, "effects": "Reads state through GET /api/privacy/protection/canary without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/privacy/protection/canary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.erase", "title": "Erase workspace Chat data", "description": "Permanently erase all Chat database rows and protected objects for the verified workspace.", "method": "DELETE", "path": "/api/privacy/workspace", "permission": "workspace:delete", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/privacy/workspace", "body": null }, "effects": "May change state through DELETE /api/privacy/workspace. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/privacy/workspace", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "Delete Workspace", "description": "Delete an empty non-default Topolo Chat workspace.", "method": "DELETE", "path": "/api/chat/workspaces/{workspaceId}", "permission": "workspace:delete", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/chat/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/chat/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/chat/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channels.list", "title": "List channels", "description": "List workspace channels.", "method": "GET", "path": "/api/channels", "permission": "channels:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List channels.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/channels", "body": null }, "effects": "Reads state through GET /api/channels without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/channels", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channels.create", "title": "Create channel", "description": "Create a workspace channel.", "method": "POST", "path": "/api/channels", "permission": "channels:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "topic": { "type": "string", "minLength": 1 }, "isPrivate": { "type": "boolean" }, "memberIds": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "name", "topic" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create channel.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "name": "example", "topic": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/channels", "body": { "name": "example", "topic": "example" } }, "effects": "May change state through POST /api/channels. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/channels", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channel_messages.list", "title": "List channel messages", "description": "List messages in a channel.", "method": "GET", "path": "/api/channels/{channelId}/messages", "permission": "messages:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "before": { "type": "string" } }, "required": [ "channelId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List channel messages.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/channels/example/messages", "body": null }, "effects": "Reads state through GET /api/channels/{channelId}/messages without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/channels/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channel_messages.send", "title": "Send channel message", "description": "Send a message to a channel.", "method": "POST", "path": "/api/channels/{channelId}/messages", "permission": "messages:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "threadParentId": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "body" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Send channel message.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example", "body": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/channels/example/messages", "body": { "channelId": "example", "body": "example" } }, "effects": "May change state through POST /api/channels/{channelId}/messages. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/channels/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.list", "title": "List direct messages", "description": "List direct-message conversations.", "method": "GET", "path": "/api/dms", "permission": "direct_messages:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List direct messages.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/dms", "body": null }, "effects": "Reads state through GET /api/dms without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/dms", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.create", "title": "Create direct message", "description": "Create a direct-message conversation.", "method": "POST", "path": "/api/dms", "permission": "direct_messages:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "memberId": { "type": "string", "minLength": 1 } }, "required": [ "memberId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create direct message.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "memberId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/dms", "body": { "memberId": "example" } }, "effects": "May change state through POST /api/dms. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/dms", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.list", "title": "List meetings", "description": "List meetings.", "method": "GET", "path": "/api/meetings", "permission": "meetings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List meetings.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/meetings", "body": null }, "effects": "Reads state through GET /api/meetings without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/meetings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.create", "title": "Create meeting", "description": "Create a meeting.", "method": "POST", "path": "/api/meetings", "permission": "meetings:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "sourceKind": { "type": "string", "enum": [ "channel", "dm", "workspace" ] }, "sourceId": { "type": "string", "minLength": 1 }, "startsAt": { "type": "string" }, "durationMinutes": { "type": "number" }, "reminderMinutes": { "type": "number" }, "recurrenceRule": { "type": "string", "enum": [ "none", "daily", "weekdays", "weekly" ] }, "startNow": { "type": "boolean" } }, "required": [ "title", "description", "sourceKind", "sourceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create meeting.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "title": "example", "description": "example", "sourceKind": "channel", "sourceId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings", "body": { "title": "example", "description": "example", "sourceKind": "channel", "sourceId": "example" } }, "effects": "May change state through POST /api/meetings. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.end", "title": "End meeting", "description": "End a meeting.", "method": "POST", "path": "/api/meetings/{meetingId}/end", "permission": "meetings:write", "readOnly": false, "destructive": true, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by End meeting.", "additionalProperties": true }, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/end", "body": { "meetingId": "example" } }, "effects": "May change state through POST /api/meetings/{meetingId}/end. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/end", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "search.query", "title": "Search chat", "description": "Search channels, messages, and meetings.", "method": "GET", "path": "/api/search", "permission": "search:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "type": "string" }, "scope": { "type": "string", "enum": [ "messages", "files", "people", "channels" ] }, "conversationKind": { "type": "string", "enum": [ "channel", "dm" ] }, "conversationId": { "type": "string" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Search chat.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "q": "example", "scope": "messages", "conversationKind": "channel" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/search", "body": null }, "effects": "Reads state through GET /api/search without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/search", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "uploads.request", "title": "Request upload", "description": "Request a chat upload slot.", "method": "POST", "path": "/api/uploads/request", "permission": "uploads:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1 }, "contentType": { "type": "string", "minLength": 1 }, "sizeBytes": { "type": "number", "exclusiveMinimum": 0, "maximum": 26214400 } }, "required": [ "fileName", "contentType", "sizeBytes" ], "additionalProperties": false }, "agentContract": { "upload": { "profile": "url-session", "fileNameField": "fileName", "contentTypeField": "contentType", "sizeField": "sizeBytes", "maxBytes": 26214400, "acceptedContentTypes": [ "*/*" ], "uploadUrlPath": "upload.uploadUrl", "uploadMethod": "PUT", "complete": { "actionId": "app_topolo_chat.uploads.complete", "inputField": "uploadId", "responsePath": "upload.id" } } }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Request upload.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "fileName": "example", "contentType": "example", "sizeBytes": 1 }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/uploads/request", "body": { "fileName": "example", "contentType": "example", "sizeBytes": 1 } }, "effects": "May change state through POST /api/uploads/request. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/uploads/request", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "agent_personas.list", "title": "List agent personas", "description": "List the workspace's TopoloAgent AI personas available to surface in Chat. Proxies to the Topolo Agent persona host.", "method": "GET", "path": "/api/agent-personas", "permission": "workspace:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/agent-personas", "body": null }, "effects": "Reads state through GET /api/agent-personas without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/agent-personas", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "agent_personas.send_message", "title": "Message an agent persona", "description": "Send a message to a TopoloAgent persona on behalf of the acting user and receive the persona reply. Proxies to the Topolo Agent dual-identity session invoke surface.", "method": "POST", "path": "/api/agent-personas/{personaId}/messages", "permission": "workspace:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "personaId": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "threadId": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "approve" ] }, "approvalId": { "type": "string" }, "decision": { "type": "string" } }, "required": [ "personaId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "personaId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/agent-personas/example/messages", "body": { "personaId": "example" } }, "effects": "May change state through POST /api/agent-personas/{personaId}/messages. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/agent-personas/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "presence.get", "title": "Presence Get", "description": "Execute Presence Get in Topolo Chat.", "method": "GET", "path": "/api/widget/presence", "permission": "workspace:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/widget/presence", "body": null }, "effects": "Reads state through GET /api/widget/presence without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/widget/presence", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "presence.update", "title": "Presence Update", "description": "Execute Presence Update in Topolo Chat.", "method": "POST", "path": "/api/widget/presence", "permission": "workspace:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "busy", "do_not_disturb", "be_right_back", "away", "offline" ] } }, "required": [ "status" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "status": "available" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/widget/presence", "body": { "status": "available" } }, "effects": "May change state through POST /api/widget/presence. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/widget/presence", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "calls.join", "title": "Calls Join", "description": "Execute Calls Join in Topolo Chat.", "method": "POST", "path": "/api/widget/dms/{conversationId}/calls/{callId}/join", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "callId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "callId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example", "callId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/widget/dms/example/calls/example/join", "body": { "conversationId": "example", "callId": "example" } }, "effects": "May change state through POST /api/widget/dms/{conversationId}/calls/{callId}/join. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/widget/dms/*/calls/*/join", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "calls.end", "title": "Calls End", "description": "Execute Calls End in Topolo Chat.", "method": "POST", "path": "/api/widget/dms/{conversationId}/calls/{callId}/end", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "callId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "enum": [ "no_answer", "missed", "declined" ] }, "mode": { "type": "string", "enum": [ "audio", "video" ] } }, "required": [ "conversationId", "callId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example", "callId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/widget/dms/example/calls/example/end", "body": { "conversationId": "example", "callId": "example" } }, "effects": "May change state through POST /api/widget/dms/{conversationId}/calls/{callId}/end. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/widget/dms/*/calls/*/end", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channels.update", "title": "Channels Update", "description": "Execute Channels Update in Topolo Chat.", "method": "POST", "path": "/api/channels/{channelId}", "permission": "channels:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "topic": { "type": "string", "minLength": 1 }, "isPrivate": { "type": "boolean" } }, "required": [ "channelId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/channels/example", "body": { "channelId": "example" } }, "effects": "May change state through POST /api/channels/{channelId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/channels/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channels.archive", "title": "Channels Archive", "description": "Execute Channels Archive in Topolo Chat.", "method": "POST", "path": "/api/channels/{channelId}/archive", "permission": "channels:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 } }, "required": [ "channelId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/channels/example/archive", "body": { "channelId": "example" } }, "effects": "May change state through POST /api/channels/{channelId}/archive. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/channels/*/archive", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channels.delete", "title": "Channels Delete", "description": "Execute Channels Delete in Topolo Chat.", "method": "DELETE", "path": "/api/channels/{channelId}", "permission": "channels:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 } }, "required": [ "channelId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/channels/example", "body": null }, "effects": "May change state through DELETE /api/channels/{channelId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/channels/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channel_messages.thread", "title": "Channel Messages Thread", "description": "Execute Channel Messages Thread in Topolo Chat.", "method": "GET", "path": "/api/channels/{channelId}/messages/{messageId}/thread", "permission": "messages:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "messageId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example", "messageId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/channels/example/messages/example/thread", "body": null }, "effects": "Reads state through GET /api/channels/{channelId}/messages/{messageId}/thread without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/channels/*/messages/*/thread", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channel_messages.forward", "title": "Channel Messages Forward", "description": "Execute Channel Messages Forward in Topolo Chat.", "method": "POST", "path": "/api/channels/{channelId}/messages/forward", "permission": "messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "sourceKind": { "type": "string", "enum": [ "channel", "dm" ] }, "sourceConversationId": { "type": "string", "minLength": 1 }, "sourceMessageId": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "sourceKind", "sourceConversationId", "sourceMessageId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example", "sourceKind": "channel", "sourceConversationId": "example", "sourceMessageId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/channels/example/messages/forward", "body": { "channelId": "example", "sourceKind": "channel", "sourceConversationId": "example", "sourceMessageId": "example" } }, "effects": "May change state through POST /api/channels/{channelId}/messages/forward. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/channels/*/messages/forward", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channel_messages.save", "title": "Channel Messages Save", "description": "Execute Channel Messages Save in Topolo Chat.", "method": "POST", "path": "/api/channels/{channelId}/messages/{messageId}/save", "permission": "messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "messageId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example", "messageId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/channels/example/messages/example/save", "body": { "channelId": "example", "messageId": "example" } }, "effects": "May change state through POST /api/channels/{channelId}/messages/{messageId}/save. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/channels/*/messages/*/save", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channel_messages.update", "title": "Channel Messages Update", "description": "Execute Channel Messages Update in Topolo Chat.", "method": "POST", "path": "/api/channels/{channelId}/messages/{messageId}/update", "permission": "messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "messageId", "body" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example", "messageId": "example", "body": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/channels/example/messages/example/update", "body": { "channelId": "example", "messageId": "example", "body": "example" } }, "effects": "May change state through POST /api/channels/{channelId}/messages/{messageId}/update. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/channels/*/messages/*/update", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channel_messages.delete", "title": "Channel Messages Delete", "description": "Execute Channel Messages Delete in Topolo Chat.", "method": "POST", "path": "/api/channels/{channelId}/messages/{messageId}/delete", "permission": "messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "messageId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example", "messageId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/channels/example/messages/example/delete", "body": { "channelId": "example", "messageId": "example" } }, "effects": "May change state through POST /api/channels/{channelId}/messages/{messageId}/delete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/channels/*/messages/*/delete", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channel_messages.react", "title": "Channel Messages React", "description": "Execute Channel Messages React in Topolo Chat.", "method": "POST", "path": "/api/channels/{channelId}/messages/{messageId}/reactions", "permission": "messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 }, "emoji": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "messageId", "emoji" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example", "messageId": "example", "emoji": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/channels/example/messages/example/reactions", "body": { "channelId": "example", "messageId": "example", "emoji": "example" } }, "effects": "May change state through POST /api/channels/{channelId}/messages/{messageId}/reactions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/channels/*/messages/*/reactions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channel_messages.pin", "title": "Channel Messages Pin", "description": "Execute Channel Messages Pin in Topolo Chat.", "method": "POST", "path": "/api/channels/{channelId}/messages/{messageId}/pin", "permission": "messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "messageId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example", "messageId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/channels/example/messages/example/pin", "body": { "channelId": "example", "messageId": "example" } }, "effects": "May change state through POST /api/channels/{channelId}/messages/{messageId}/pin. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/channels/*/messages/*/pin", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channel_messages.mark_unread", "title": "Channel Messages Mark Unread", "description": "Execute Channel Messages Mark Unread in Topolo Chat.", "method": "POST", "path": "/api/channels/{channelId}/messages/{messageId}/unread", "permission": "messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "messageId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example", "messageId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/channels/example/messages/example/unread", "body": { "channelId": "example", "messageId": "example" } }, "effects": "May change state through POST /api/channels/{channelId}/messages/{messageId}/unread. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/channels/*/messages/*/unread", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channels.mark_read", "title": "Channels Mark Read", "description": "Execute Channels Mark Read in Topolo Chat.", "method": "POST", "path": "/api/channels/{channelId}/read", "permission": "messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 } }, "required": [ "channelId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/channels/example/read", "body": { "channelId": "example" } }, "effects": "May change state through POST /api/channels/{channelId}/read. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/channels/*/read", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channels.mute", "title": "Channels Mute", "description": "Execute Channels Mute in Topolo Chat.", "method": "POST", "path": "/api/channels/{channelId}/mute", "permission": "messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "muted": { "type": "boolean" } }, "required": [ "channelId", "muted" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "channelId": "example", "muted": true }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/channels/example/mute", "body": { "channelId": "example", "muted": true } }, "effects": "May change state through POST /api/channels/{channelId}/mute. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/channels/*/mute", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.manage", "title": "Direct Messages Manage", "description": "Execute Direct Messages Manage in Topolo Chat.", "method": "GET", "path": "/api/dms/manage", "permission": "direct_messages:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/dms/manage", "body": null }, "effects": "Reads state through GET /api/dms/manage without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/dms/manage", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.messages", "title": "Direct Messages Messages", "description": "Execute Direct Messages Messages in Topolo Chat.", "method": "GET", "path": "/api/dms/{conversationId}/messages", "permission": "direct_messages:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "before": { "type": "string" } }, "required": [ "conversationId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/dms/example/messages", "body": null }, "effects": "Reads state through GET /api/dms/{conversationId}/messages without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/dms/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.thread", "title": "Direct Messages Thread", "description": "Execute Direct Messages Thread in Topolo Chat.", "method": "GET", "path": "/api/dms/{conversationId}/messages/{messageId}/thread", "permission": "direct_messages:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "messageId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example", "messageId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/dms/example/messages/example/thread", "body": null }, "effects": "Reads state through GET /api/dms/{conversationId}/messages/{messageId}/thread without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/dms/*/messages/*/thread", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.forward", "title": "Direct Messages Forward", "description": "Execute Direct Messages Forward in Topolo Chat.", "method": "POST", "path": "/api/dms/{conversationId}/messages/forward", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "sourceKind": { "type": "string", "enum": [ "channel", "dm" ] }, "sourceConversationId": { "type": "string", "minLength": 1 }, "sourceMessageId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "sourceKind", "sourceConversationId", "sourceMessageId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example", "sourceKind": "channel", "sourceConversationId": "example", "sourceMessageId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/dms/example/messages/forward", "body": { "conversationId": "example", "sourceKind": "channel", "sourceConversationId": "example", "sourceMessageId": "example" } }, "effects": "May change state through POST /api/dms/{conversationId}/messages/forward. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/dms/*/messages/forward", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.save", "title": "Direct Messages Save", "description": "Execute Direct Messages Save in Topolo Chat.", "method": "POST", "path": "/api/dms/{conversationId}/messages/{messageId}/save", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "messageId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example", "messageId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/dms/example/messages/example/save", "body": { "conversationId": "example", "messageId": "example" } }, "effects": "May change state through POST /api/dms/{conversationId}/messages/{messageId}/save. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/dms/*/messages/*/save", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.send", "title": "Direct Messages Send", "description": "Execute Direct Messages Send in Topolo Chat.", "method": "POST", "path": "/api/dms/{conversationId}/messages", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "threadParentId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "body" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example", "body": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/dms/example/messages", "body": { "conversationId": "example", "body": "example" } }, "effects": "May change state through POST /api/dms/{conversationId}/messages. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/dms/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.update", "title": "Direct Messages Update", "description": "Execute Direct Messages Update in Topolo Chat.", "method": "POST", "path": "/api/dms/{conversationId}/messages/{messageId}/update", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "messageId", "body" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example", "messageId": "example", "body": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/dms/example/messages/example/update", "body": { "conversationId": "example", "messageId": "example", "body": "example" } }, "effects": "May change state through POST /api/dms/{conversationId}/messages/{messageId}/update. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/dms/*/messages/*/update", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.delete", "title": "Direct Messages Delete", "description": "Execute Direct Messages Delete in Topolo Chat.", "method": "POST", "path": "/api/dms/{conversationId}/messages/{messageId}/delete", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "messageId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example", "messageId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/dms/example/messages/example/delete", "body": { "conversationId": "example", "messageId": "example" } }, "effects": "May change state through POST /api/dms/{conversationId}/messages/{messageId}/delete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/dms/*/messages/*/delete", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.react", "title": "Direct Messages React", "description": "Execute Direct Messages React in Topolo Chat.", "method": "POST", "path": "/api/dms/{conversationId}/messages/{messageId}/reactions", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 }, "emoji": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "messageId", "emoji" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example", "messageId": "example", "emoji": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/dms/example/messages/example/reactions", "body": { "conversationId": "example", "messageId": "example", "emoji": "example" } }, "effects": "May change state through POST /api/dms/{conversationId}/messages/{messageId}/reactions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/dms/*/messages/*/reactions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.mark_unread", "title": "Direct Messages Mark Unread", "description": "Execute Direct Messages Mark Unread in Topolo Chat.", "method": "POST", "path": "/api/dms/{conversationId}/messages/{messageId}/unread", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "messageId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example", "messageId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/dms/example/messages/example/unread", "body": { "conversationId": "example", "messageId": "example" } }, "effects": "May change state through POST /api/dms/{conversationId}/messages/{messageId}/unread. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/dms/*/messages/*/unread", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.mark_read", "title": "Direct Messages Mark Read", "description": "Execute Direct Messages Mark Read in Topolo Chat.", "method": "POST", "path": "/api/dms/{conversationId}/read", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/dms/example/read", "body": { "conversationId": "example" } }, "effects": "May change state through POST /api/dms/{conversationId}/read. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/dms/*/read", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.mute", "title": "Direct Messages Mute", "description": "Execute Direct Messages Mute in Topolo Chat.", "method": "POST", "path": "/api/dms/{conversationId}/mute", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "muted": { "type": "boolean" } }, "required": [ "conversationId", "muted" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example", "muted": true }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/dms/example/mute", "body": { "conversationId": "example", "muted": true } }, "effects": "May change state through POST /api/dms/{conversationId}/mute. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/dms/*/mute", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "direct_messages.archive", "title": "Direct Messages Archive", "description": "Execute Direct Messages Archive in Topolo Chat.", "method": "POST", "path": "/api/dms/{conversationId}/archive", "permission": "direct_messages:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "archived": { "type": "boolean" } }, "required": [ "conversationId", "archived" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "conversationId": "example", "archived": true }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/dms/example/archive", "body": { "conversationId": "example", "archived": true } }, "effects": "May change state through POST /api/dms/{conversationId}/archive. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/dms/*/archive", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "audit_events.list", "title": "Audit Events List", "description": "Execute Audit Events List in Topolo Chat.", "method": "GET", "path": "/api/audit-events", "permission": "audit:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/audit-events", "body": null }, "effects": "Reads state through GET /api/audit-events without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/audit-events", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "files.download", "title": "Files Download", "description": "Execute Files Download in Topolo Chat.", "method": "GET", "path": "/api/files/{fileKey}", "permission": "messages:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileKey": { "type": "string", "minLength": 1 } }, "required": [ "fileKey" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "fileKey": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/files/example", "body": null }, "effects": "Reads state through GET /api/files/{fileKey} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/files/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.get", "title": "Meetings Get", "description": "Execute Meetings Get in Topolo Chat.", "method": "GET", "path": "/api/meetings/{meetingId}", "permission": "meetings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/meetings/example", "body": null }, "effects": "Reads state through GET /api/meetings/{meetingId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/meetings/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meeting_messages.list", "title": "Meeting Messages List", "description": "Execute Meeting Messages List in Topolo Chat.", "method": "GET", "path": "/api/meetings/{meetingId}/messages", "permission": "meetings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/meetings/example/messages", "body": null }, "effects": "Reads state through GET /api/meetings/{meetingId}/messages without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/meetings/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meeting_messages.send", "title": "Meeting Messages Send", "description": "Execute Meeting Messages Send in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/messages", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "body" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "body": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/messages", "body": { "meetingId": "example", "body": "example" } }, "effects": "May change state through POST /api/meetings/{meetingId}/messages. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meeting_messages.react", "title": "Meeting Messages React", "description": "Execute Meeting Messages React in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/messages/{messageId}/reactions", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 }, "emoji": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "messageId", "emoji" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "messageId": "example", "emoji": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/messages/example/reactions", "body": { "meetingId": "example", "messageId": "example", "emoji": "example" } }, "effects": "May change state through POST /api/meetings/{meetingId}/messages/{messageId}/reactions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/messages/*/reactions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meeting_polls.list", "title": "Meeting Polls List", "description": "Execute Meeting Polls List in Topolo Chat.", "method": "GET", "path": "/api/meetings/{meetingId}/polls", "permission": "meetings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/meetings/example/polls", "body": null }, "effects": "Reads state through GET /api/meetings/{meetingId}/polls without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/meetings/*/polls", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meeting_polls.create", "title": "Meeting Polls Create", "description": "Execute Meeting Polls Create in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/polls", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "question": { "type": "string", "minLength": 1 }, "options": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "meetingId", "question", "options" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "question": "example", "options": [ "example", "example" ] }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/polls", "body": { "meetingId": "example", "question": "example", "options": [ "example", "example" ] } }, "effects": "May change state through POST /api/meetings/{meetingId}/polls. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/polls", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meeting_polls.vote", "title": "Meeting Polls Vote", "description": "Execute Meeting Polls Vote in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/polls/{pollId}/vote", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "pollId": { "type": "string", "minLength": 1 }, "optionIndex": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "meetingId", "pollId", "optionIndex" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "pollId": "example", "optionIndex": 1 }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/polls/example/vote", "body": { "meetingId": "example", "pollId": "example", "optionIndex": 1 } }, "effects": "May change state through POST /api/meetings/{meetingId}/polls/{pollId}/vote. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/polls/*/vote", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meeting_notes.create", "title": "Meeting Notes Create", "description": "Execute Meeting Notes Create in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/notes", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "body" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "body": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/notes", "body": { "meetingId": "example", "body": "example" } }, "effects": "May change state through POST /api/meetings/{meetingId}/notes. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/notes", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.calendar", "title": "Meetings Calendar", "description": "Execute Meetings Calendar in Topolo Chat.", "method": "GET", "path": "/api/meetings/{meetingId}/calendar", "permission": "meetings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/meetings/example/calendar", "body": null }, "effects": "Reads state through GET /api/meetings/{meetingId}/calendar without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/meetings/*/calendar", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.update", "title": "Meetings Update", "description": "Execute Meetings Update in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/update", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "startsAt": { "type": "string" }, "durationMinutes": { "type": "number", "exclusiveMinimum": 0 }, "reminderMinutes": { "type": "number", "minimum": 0 }, "recurrenceRule": { "type": "string", "enum": [ "none", "daily", "weekdays", "weekly" ] }, "status": { "type": "string", "enum": [ "live", "scheduled", "completed", "cancelled" ] } }, "required": [ "meetingId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/update", "body": { "meetingId": "example" } }, "effects": "May change state through POST /api/meetings/{meetingId}/update. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/update", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.delete", "title": "Meetings Delete", "description": "Execute Meetings Delete in Topolo Chat.", "method": "DELETE", "path": "/api/meetings/{meetingId}", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/meetings/example", "body": null }, "effects": "May change state through DELETE /api/meetings/{meetingId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/meetings/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.guest_invite", "title": "Meetings Guest Invite", "description": "Execute Meetings Guest Invite in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/guest-invites", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "meetingId", "email" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "email": "user@example.com" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/guest-invites", "body": { "meetingId": "example", "email": "user@example.com" } }, "effects": "May change state through POST /api/meetings/{meetingId}/guest-invites. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/guest-invites", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.transcript", "title": "Meetings Transcript", "description": "Execute Meetings Transcript in Topolo Chat.", "method": "GET", "path": "/api/meetings/{meetingId}/transcript", "permission": "meetings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/meetings/example/transcript", "body": null }, "effects": "Reads state through GET /api/meetings/{meetingId}/transcript without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/meetings/*/transcript", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.join_token", "title": "Meetings Join Token", "description": "Execute Meetings Join Token in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/join-token", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/join-token", "body": { "meetingId": "example" } }, "effects": "May change state through POST /api/meetings/{meetingId}/join-token. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/join-token", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.admit", "title": "Meetings Admit", "description": "Execute Meetings Admit in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/admit", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "participantId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "participantId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "participantId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/admit", "body": { "meetingId": "example", "participantId": "example" } }, "effects": "May change state through POST /api/meetings/{meetingId}/admit. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/admit", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.remove_participant", "title": "Meetings Remove Participant", "description": "Execute Meetings Remove Participant in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/remove-participant", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "participantId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "participantId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "participantId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/remove-participant", "body": { "meetingId": "example", "participantId": "example" } }, "effects": "May change state through POST /api/meetings/{meetingId}/remove-participant. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/remove-participant", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.update_role", "title": "Meetings Update Role", "description": "Execute Meetings Update Role in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/update-role", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "participantId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "enum": [ "host", "co_host", "presenter", "participant", "guest" ] } }, "required": [ "meetingId", "participantId", "role" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "participantId": "example", "role": "host" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/update-role", "body": { "meetingId": "example", "participantId": "example", "role": "host" } }, "effects": "May change state through POST /api/meetings/{meetingId}/update-role. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/update-role", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.lock", "title": "Meetings Lock", "description": "Execute Meetings Lock in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/lock", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "locked": { "type": "boolean" } }, "required": [ "meetingId", "locked" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "locked": true }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/lock", "body": { "meetingId": "example", "locked": true } }, "effects": "May change state through POST /api/meetings/{meetingId}/lock. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/lock", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.recording_start", "title": "Meetings Recording Start", "description": "Execute Meetings Recording Start in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/recording/start", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/recording/start", "body": { "meetingId": "example" } }, "effects": "May change state through POST /api/meetings/{meetingId}/recording/start. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/recording/start", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.recording_stop", "title": "Meetings Recording Stop", "description": "Execute Meetings Recording Stop in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/recording/stop", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/recording/stop", "body": { "meetingId": "example" } }, "effects": "May change state through POST /api/meetings/{meetingId}/recording/stop. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/recording/stop", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "meetings.captions_toggle", "title": "Meetings Captions Toggle", "description": "Execute Meetings Captions Toggle in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/captions/toggle", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" } }, "required": [ "meetingId", "enabled" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "enabled": true }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/captions/toggle", "body": { "meetingId": "example", "enabled": true } }, "effects": "May change state through POST /api/meetings/{meetingId}/captions/toggle. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/captions/toggle", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "remote_assist.request", "title": "Remote Assist Request", "description": "Execute Remote Assist Request in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/remote-assist/request", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "hostName": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "hostName" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "hostName": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/remote-assist/request", "body": { "meetingId": "example", "hostName": "example" } }, "effects": "May change state through POST /api/meetings/{meetingId}/remote-assist/request. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/remote-assist/request", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "remote_assist.approve", "title": "Remote Assist Approve", "description": "Execute Remote Assist Approve in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/remote-assist/{sessionId}/approve", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "sessionId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "sessionId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/remote-assist/example/approve", "body": { "meetingId": "example", "sessionId": "example" } }, "effects": "May change state through POST /api/meetings/{meetingId}/remote-assist/{sessionId}/approve. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/remote-assist/*/approve", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "remote_assist.revoke", "title": "Remote Assist Revoke", "description": "Execute Remote Assist Revoke in Topolo Chat.", "method": "POST", "path": "/api/meetings/{meetingId}/remote-assist/{sessionId}/revoke", "permission": "meetings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "sessionId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "sessionId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/meetings/example/remote-assist/example/revoke", "body": { "meetingId": "example", "sessionId": "example" } }, "effects": "May change state through POST /api/meetings/{meetingId}/remote-assist/{sessionId}/revoke. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/meetings/*/remote-assist/*/revoke", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "remote_assist.state", "title": "Remote Assist State", "description": "Execute Remote Assist State in Topolo Chat.", "method": "GET", "path": "/api/meetings/{meetingId}/remote-assist/{sessionId}/state", "permission": "meetings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "sessionId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "meetingId": "example", "sessionId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/meetings/example/remote-assist/example/state", "body": null }, "effects": "Reads state through GET /api/meetings/{meetingId}/remote-assist/{sessionId}/state without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/meetings/*/remote-assist/*/state", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operational_threads.list", "title": "Operational Threads List", "description": "Execute Operational Threads List in Topolo Chat.", "method": "GET", "path": "/api/operational-threads", "permission": "operational_threads:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "view": { "type": "string", "enum": [ "open", "recent" ] }, "state": { "type": "string", "enum": [ "open", "acknowledged", "snoozed", "resolved" ] }, "updatedAfter": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "sourceSystem": { "type": "string" }, "externalRef": { "type": "string" } }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "view": "open", "state": "open", "updatedAfter": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/operational-threads", "body": null }, "effects": "Reads state through GET /api/operational-threads without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/operational-threads", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operational_threads.get", "title": "Operational Threads Get", "description": "Execute Operational Threads Get in Topolo Chat.", "method": "GET", "path": "/api/operational-threads/{threadId}", "permission": "operational_threads:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 } }, "required": [ "threadId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "threadId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/operational-threads/example", "body": null }, "effects": "Reads state through GET /api/operational-threads/{threadId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/operational-threads/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operational_threads.create", "title": "Operational Threads Create", "description": "Execute Operational Threads Create in Topolo Chat.", "method": "POST", "path": "/api/operational-threads", "permission": "operational_threads:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "minLength": 1 }, "severity": { "type": "string" }, "state": { "type": "string", "enum": [ "open", "acknowledged", "snoozed", "resolved" ] }, "sourceSystem": { "type": "string" }, "externalRef": { "type": "string" }, "ownerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snoozedUntil": { "type": "string" } }, "required": [ "title", "summary" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "title": "example", "summary": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/operational-threads", "body": { "title": "example", "summary": "example" } }, "effects": "May change state through POST /api/operational-threads. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/operational-threads", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operational_threads.update", "title": "Operational Threads Update", "description": "Execute Operational Threads Update in Topolo Chat.", "method": "POST", "path": "/api/operational-threads/{threadId}/update", "permission": "operational_threads:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "minLength": 1 }, "severity": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceSystem": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalRef": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "threadId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "threadId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/operational-threads/example/update", "body": { "threadId": "example" } }, "effects": "May change state through POST /api/operational-threads/{threadId}/update. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/operational-threads/*/update", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operational_threads.transition", "title": "Operational Threads Transition", "description": "Execute Operational Threads Transition in Topolo Chat.", "method": "POST", "path": "/api/operational-threads/{threadId}/state", "permission": "operational_threads:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 }, "state": { "type": "string", "enum": [ "open", "acknowledged", "snoozed", "resolved" ] }, "snoozedUntil": { "type": "string" } }, "required": [ "threadId", "state" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "threadId": "example", "state": "open" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/operational-threads/example/state", "body": { "threadId": "example", "state": "open" } }, "effects": "May change state through POST /api/operational-threads/{threadId}/state. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/operational-threads/*/state", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operational_threads.assign_owner", "title": "Operational Threads Assign Owner", "description": "Execute Operational Threads Assign Owner in Topolo Chat.", "method": "POST", "path": "/api/operational-threads/{threadId}/owner", "permission": "operational_threads:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 }, "ownerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "threadId", "ownerId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "threadId": "example", "ownerId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/operational-threads/example/owner", "body": { "threadId": "example", "ownerId": "example" } }, "effects": "May change state through POST /api/operational-threads/{threadId}/owner. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/operational-threads/*/owner", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operational_threads.comment", "title": "Operational Threads Comment", "description": "Execute Operational Threads Comment in Topolo Chat.", "method": "POST", "path": "/api/operational-threads/{threadId}/comments", "permission": "operational_threads:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 } }, "required": [ "threadId", "body" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "threadId": "example", "body": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/operational-threads/example/comments", "body": { "threadId": "example", "body": "example" } }, "effects": "May change state through POST /api/operational-threads/{threadId}/comments. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/operational-threads/*/comments", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "notification_preferences.update", "title": "Notification Preferences Update", "description": "Execute Notification Preferences Update in Topolo Chat.", "method": "POST", "path": "/api/notification-preferences", "permission": "workspace:read", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "directMessages": { "type": "boolean" }, "channelMentions": { "type": "boolean" }, "meetingReminders": { "type": "boolean" }, "recordingAlerts": { "type": "boolean" } }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "directMessages": true, "channelMentions": true, "meetingReminders": true }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/notification-preferences", "body": { "directMessages": true, "channelMentions": true, "meetingReminders": true } }, "effects": "May change state through POST /api/notification-preferences. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/notification-preferences", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspace_policies.update", "title": "Workspace Policies Update", "description": "Execute Workspace Policies Update in Topolo Chat.", "method": "POST", "path": "/api/workspace-policies", "permission": "settings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "guestsEnabled": { "type": "boolean" }, "waitingRoomDefault": { "type": "boolean" }, "recordingEnabled": { "type": "boolean" }, "transcriptsEnabled": { "type": "boolean" }, "screenShareEnabled": { "type": "boolean" }, "remoteAssistEnabled": { "type": "boolean" } }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "guestsEnabled": true, "waitingRoomDefault": true, "recordingEnabled": true }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspace-policies", "body": { "guestsEnabled": true, "waitingRoomDefault": true, "recordingEnabled": true } }, "effects": "May change state through POST /api/workspace-policies. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspace-policies", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "uploads.content", "title": "Uploads Content", "description": "Execute Uploads Content in Topolo Chat.", "method": "PUT", "path": "/api/uploads/{uploadId}/content", "permission": "uploads:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "uploadId": { "type": "string", "minLength": 1 } }, "required": [ "uploadId" ], "additionalProperties": {} }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "uploadId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/uploads/example/content", "body": { "uploadId": "example" } }, "effects": "May change state through PUT /api/uploads/{uploadId}/content. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/uploads/*/content", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "uploads.complete", "title": "Uploads Complete", "description": "Execute Uploads Complete in Topolo Chat.", "method": "POST", "path": "/api/uploads/complete", "permission": "uploads:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "uploadId": { "type": "string", "minLength": 1 }, "conversationKind": { "type": "string", "enum": [ "channel", "dm" ] }, "conversationId": { "type": "string", "minLength": 1 }, "messageBody": { "type": "string" }, "threadParentId": { "type": "string", "minLength": 1 }, "thread_parent_id": { "type": "string", "minLength": 1 } }, "required": [ "uploadId", "conversationKind", "conversationId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "uploadId": "example", "conversationKind": "channel", "conversationId": "example" }, "cli_example": [ "topolo actions --service topolo-chat --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/uploads/complete", "body": { "uploadId": "example", "conversationKind": "channel", "conversationId": "example" } }, "effects": "May change state through POST /api/uploads/complete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/uploads/complete", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 130, "matched_actions": 100, "declared_unserved_actions": [ "GET /api/widget" ], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 30, "configured_exclusions": 38, "configuration_findings": [ "* /api/*: exclusion matches no served route", "* /api/guest/*: exclusion matches no served route", "* /api/launch/*: exclusion matches no served route", "GET /desktop: exclusion matches no served route", "GET /api/desktop/download: exclusion matches no served route", "GET /api/desktop/releases/latest: exclusion matches no served route", "* /api/internal/*: exclusion matches no served route", "* /api/meetings/webhooks/*: exclusion matches no served route" ], "notes": [ "4 manually-declared route(s)" ] }, "runtime_contract_audit": { "status": "verified", "actions": 101, "contracts": 101, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/index.ts" ], "authorization_sources": [ "apps/api/src/index.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloChat/topolo.mobile-experience.json", "contract": { "version": "2026-06-27", "status": "approved", "mode": "native_capability", "appId": "app_topolo_chat", "localizationNamespace": "chat", "permissions": [ "chat.threads.read", "chat.messages.write" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/threads", "auth": { "audience": "topolo-chat", "scopes": [ "chat.threads:read", "chat.messages:write" ] }, "routes": [ { "path": "/threads", "title": "Threads", "titleKey": "chat.mobile.routes.threads.title", "template": "chat.threadList", "dataSource": "chat.threads.list", "apiPath": "/api/channels", "detailRoute": "/threads/:id" }, { "path": "/threads/:id", "title": "Thread", "titleKey": "chat.mobile.routes.thread.title", "template": "chat.thread", "dataSource": "chat.threads.detail", "apiPath": "/api/channels/:id/messages", "actions": [ { "id": "chat.messages.send", "title": "Send message", "titleKey": "chat.mobile.actions.sendMessage.title", "type": "message.send", "permission": "chat.messages.write", "method": "POST", "path": "/api/threads/:id/messages" } ] } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "LITERAL", "path": "/presence", "source_path": "apps/TopoloChat/apps/api/src/durable-objects.ts" }, { "method": "ALL", "path": "*", "source_path": "apps/TopoloChat/apps/api/src/index.ts" }, { "method": "LITERAL", "path": "/desktop", "source_path": "apps/TopoloChat/apps/api/src/index.ts" }, { "method": "LITERAL", "path": "/healthz", "source_path": "apps/TopoloChat/apps/api/src/index.ts" }, { "method": "LITERAL", "path": "/readyz", "source_path": "apps/TopoloChat/apps/api/src/index.ts" }, { "method": "LITERAL", "path": "/api/widget", "source_path": "apps/TopoloChat/apps/api/src/index.ts" }, { "method": "LITERAL", "path": "/api/desktop/releases/latest", "source_path": "apps/TopoloChat/apps/api/src/index.ts" }, { "method": "LITERAL", "path": "/api/desktop/download", "source_path": "apps/TopoloChat/apps/api/src/index.ts" } ], "ui_routes": [ { "path": "/app", "source_path": "apps/TopoloChat/apps/web/src/client/App.tsx" }, { "path": "/app/inbox", "source_path": "apps/TopoloChat/apps/web/src/client/App.tsx" }, { "path": "/app/channels", "source_path": "apps/TopoloChat/apps/web/src/client/App.tsx" }, { "path": "/app/dms", "source_path": "apps/TopoloChat/apps/web/src/client/App.tsx" }, { "path": "/app/meetings", "source_path": "apps/TopoloChat/apps/web/src/client/App.tsx" }, { "path": "/app/settings", "source_path": "apps/TopoloChat/apps/web/src/client/App.tsx" }, { "path": "/app/settings/:section", "source_path": "apps/TopoloChat/apps/web/src/client/App.tsx" }, { "path": "/app/templates", "source_path": "apps/TopoloChat/apps/web/src/client/App.tsx" }, { "path": "/app/getting-started", "source_path": "apps/TopoloChat/apps/web/src/client/App.tsx" }, { "path": "/guest/meetings/:token", "source_path": "apps/TopoloChat/apps/web/src/client/App.tsx" }, { "path": "/join", "source_path": "apps/TopoloChat/apps/web/src/client/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "internal/apps/chat", "applications/chat" ], "present_paths": [ "internal/apps/chat", "applications/chat" ], "missing_paths": [], "human_reference": "/systems/topolo-chat", "machine_reference": "/machine/systems/topolo-chat.json", "action_examples": 101, "action_schemas": 101 }, "source_findings": [ { "type": "declared_unserved_actions", "source_path": "apps/TopoloChat/topolo.app.json", "detail": [ "GET /api/widget" ] }, { "type": "action_coverage_configuration", "source_path": "apps/TopoloChat/topolo.app.json", "detail": [ "* /api/*: exclusion matches no served route", "* /api/guest/*: exclusion matches no served route", "* /api/launch/*: exclusion matches no served route", "GET /desktop: exclusion matches no served route", "GET /api/desktop/download: exclusion matches no served route", "GET /api/desktop/releases/latest: exclusion matches no served route", "* /api/internal/*: exclusion matches no served route", "* /api/meetings/webhooks/*: exclusion matches no served route" ] } ] }, "topolo-cli": { "id": "topolo-cli", "name": "Topolo CLI", "slug": "topolo-cli", "kind": "tool", "visibility": "public", "repo_paths": [ "topolo-platform/packages/topolo-cli" ], "source_revisions": [ { "source_path": "topolo-platform/packages/topolo-cli", "repository": "topolo-platform", "revision": "515376de81efed9734741b2a1d691c8195243073", "ref": "origin/staging" } ], "source_counts": { "source_files": 22, "test_files": 21, "test_cases": 0, "migration_files": 0, "database_tables": 0, "manifests": 0, "deploy_targets": 0, "actions": 0, "mobile_contracts": 0, "notifications": 0, "package_manifests": 1, "deployment_configs": 0 }, "manifests": [], "mobile_contracts": [], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [], "ui_routes": [], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "guides/agents-and-automation", "internal/apps/topolo-cli" ], "present_paths": [ "guides/agents-and-automation", "internal/apps/topolo-cli" ], "missing_paths": [], "human_reference": "/systems/topolo-cli", "machine_reference": "/machine/systems/topolo-cli.json", "action_examples": 0, "action_schemas": 0 }, "source_findings": [] }, "topolo-commerce": { "id": "topolo-commerce", "name": "TopoloCommerce", "slug": "topolo-commerce", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloCommerce" ], "source_revisions": [ { "source_path": "apps/TopoloCommerce", "repository": "apps/TopoloCommerce", "revision": "76e2638beb52f038bbe3095e1a3b2e8fb83ce886", "ref": "origin/staging" } ], "source_counts": { "source_files": 317, "test_files": 121, "test_cases": 0, "migration_files": 44, "database_tables": 0, "manifests": 1, "deploy_targets": 4, "actions": 66, "mobile_contracts": 1, "notifications": 8, "package_manifests": 8, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloCommerce/topolo.app.json", "service_slug": "topolo-commerce", "name": "topolo-commerce", "app_id": "app_topolo_commerce", "compatibility_date": "2026-04-10", "primary_target": "ops", "environments": [ "development", "production", "staging" ], "targets": [ { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/index.js", "worker_name": "topolo-commerce-api", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "APP_ID", "COMMERCE_PUBLIC_BASE_URL", "CORS_ORIGINS", "DEVICE_OFFLINE_AFTER_SECONDS", "ENVIRONMENT", "GUEST_WEB_ORIGIN", "MDM_API_URL", "NEXUS_GATEWAY_URL", "NEXUS_VOICE_FALLBACK_MODEL", "NEXUS_VOICE_FALLBACK_PROVIDER", "NEXUS_VOICE_FINAL_FALLBACK_MODEL", "NEXUS_VOICE_FINAL_FALLBACK_PROVIDER", "NEXUS_VOICE_MODEL", "NEXUS_VOICE_PROVIDER", "NEXUS_VOICE_TRANSCRIPTION_MODEL", "QURO_API_URL", "QURO_REDIRECT_ORIGIN", "SEED_CONTRACT_VERSION", "SERVICE_SLUG", "TOPOLO_AUTH_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "COMMERCE_CORE_DB", "target": null }, { "kind": "d1", "binding": "COMMERCE_ORDERS_DB", "target": null }, { "kind": "d1", "binding": "COMMERCE_SYNC_DB", "target": null }, { "kind": "d1", "binding": "COMMERCE_PAYMENTS_DB", "target": null }, { "kind": "r2", "binding": "COMMERCE_ASSETS", "target": null }, { "kind": "durableObjects", "binding": "VENUE_QUEUE_COORDINATOR", "target": null }, { "kind": "services", "binding": "TOPOLO_NEXUS", "target": null }, { "kind": "services", "binding": "TOPOLO_NEXUS", "target": null }, { "kind": "services", "binding": "TOPOLO_MDM", "target": null }, { "kind": "services", "binding": "TOPOLO_MDM", "target": null } ] }, { "name": "ops", "kind": "worker", "directory": "apps/ops", "main": "src/worker.ts", "worker_name": "topolo-commerce-ops-web", "subdomain": "commerce", "healthcheck_path": null, "variable_names": [ "AUTH_API_URL", "VITE_COMMERCE_API_URL" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null } ] }, { "name": "guest", "kind": "worker", "directory": "apps/guest", "main": "src/worker.ts", "worker_name": "topolo-commerce-guest-web", "subdomain": "guest", "healthcheck_path": null, "variable_names": [ "AUTH_API_URL", "VITE_COMMERCE_API_URL" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null } ] }, { "name": "station", "kind": "worker", "directory": "apps/station", "main": "src/worker.ts", "worker_name": "topolo-commerce-station-web", "subdomain": "station-commerce", "healthcheck_path": null, "variable_names": [ "AUTH_API_URL", "VITE_COMMERCE_API_URL" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null } ] } ], "notifications": [ "commerce.catalog.publish_failed", "commerce.device.offline", "commerce.order.cancelled", "commerce.order.confirmed", "commerce.order.created", "commerce.order.ready", "commerce.service_request.created", "commerce.service_request.status_changed" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_commerce", "events": [ { "type": "commerce.catalog.publish_failed", "version": 1, "description": "A rejected live-catalog publication attempt was persisted before delivery to its operator.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "attempt_id", "catalog_id", "revision", "failure_reason", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "attempt_id": { "type": "string", "minLength": 1 }, "catalog_id": { "type": "string", "minLength": 1 }, "revision": { "type": "integer", "minimum": 1 }, "failure_reason": { "type": "string", "minLength": 1 }, "surface": { "type": "string", "const": "action" }, "action_kind": { "type": "string", "const": "resolve" }, "action_status": { "type": "string", "const": "open" }, "priority": { "type": "string", "const": "high" }, "category": { "type": "string", "const": "commerce" }, "severity": { "type": "string", "const": "critical" }, "object_type": { "type": "string", "const": "commerce_catalog_publish" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Catalog publication failed: Dinner", "body": "A published catalog requires at least one section with one item.", "object_id": "attempt_1", "attempt_id": "attempt_1", "catalog_id": "catalog_1", "revision": 3, "failure_reason": "A published catalog requires at least one section with one item.", "surface": "action", "action_kind": "resolve", "action_status": "open", "priority": "high", "category": "commerce", "severity": "critical", "object_type": "commerce_catalog_publish", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://commerce.topolo.app/venues/venue_1/catalog" } ], "dataClassification": "internal", "sensitiveFields": [ "failure_reason" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^commerce:catalog-publish-failed:" } }, { "type": "commerce.device.offline", "version": 1, "description": "A venue edge device exceeded its configured heartbeat threshold and a durable incident was committed before delivery.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "device_id", "device_label", "last_seen_at", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "device_id": { "type": "string", "minLength": 1 }, "device_label": { "type": "string", "minLength": 1 }, "last_seen_at": { "type": "string", "format": "date-time" }, "surface": { "type": "string", "const": "action" }, "action_kind": { "type": "string", "const": "resolve" }, "action_status": { "type": "string", "const": "open" }, "priority": { "type": "string", "const": "urgent" }, "category": { "type": "string", "const": "commerce" }, "severity": { "type": "string", "const": "critical" }, "object_type": { "type": "string", "const": "commerce_device" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Device offline: Kitchen Station", "body": "Kitchen Station has not checked in for 900 seconds.", "object_id": "device_1", "device_id": "device_1", "device_label": "Kitchen Station", "last_seen_at": "2026-07-20T00:00:00.000Z", "surface": "action", "action_kind": "resolve", "action_status": "open", "priority": "urgent", "category": "commerce", "severity": "critical", "object_type": "commerce_device", "occurred_at": "2026-07-20T00:15:00.000Z", "cta_url": "https://commerce.topolo.app/venues/venue_1/devices" } ], "dataClassification": "internal", "sensitiveFields": [ "device_label" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^commerce:device-offline:" } }, { "type": "commerce.order.created", "version": 1, "description": "A new order and its operations ticket were committed before venue-staff delivery.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "order_id", "status", "total_cents", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "order_id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "const": "queued" }, "total_cents": { "type": "integer", "minimum": 0 }, "surface": { "type": "string", "const": "notification" }, "priority": { "type": "string", "const": "normal" }, "category": { "type": "string", "const": "commerce" }, "severity": { "type": "string", "const": "info" }, "object_type": { "type": "string", "const": "commerce_order" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "New commerce order", "body": "Guest order: Charred Corn Toast", "object_id": "order_1", "order_id": "order_1", "status": "queued", "total_cents": 1200, "surface": "notification", "priority": "normal", "category": "commerce", "severity": "info", "object_type": "commerce_order", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://commerce.topolo.app/venues/venue_1/queues" } ], "dataClassification": "confidential", "sensitiveFields": [ "body" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^commerce:order-created:" } }, { "type": "commerce.order.confirmed", "version": 1, "description": "An order moved durably from the queue into active fulfilment before delivery.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "order_id", "previous_status", "status", "total_cents", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "order_id": { "type": "string", "minLength": 1 }, "previous_status": { "type": "string", "minLength": 1 }, "status": { "type": "string", "const": "active" }, "total_cents": { "type": "integer", "minimum": 0 }, "surface": { "type": "string", "const": "action" }, "action_kind": { "type": "string", "const": "complete" }, "action_status": { "type": "string", "const": "open" }, "priority": { "type": "string", "const": "normal" }, "category": { "type": "string", "const": "commerce" }, "severity": { "type": "string", "const": "info" }, "object_type": { "type": "string", "const": "commerce_order" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Order confirmed", "body": "Guest order: Charred Corn Toast", "object_id": "order_1", "order_id": "order_1", "previous_status": "queued", "status": "active", "total_cents": 1200, "surface": "action", "action_kind": "complete", "action_status": "open", "priority": "normal", "category": "commerce", "severity": "info", "object_type": "commerce_order", "occurred_at": "2026-07-20T00:01:00.000Z", "cta_url": "https://commerce.topolo.app/venues/venue_1/queues" } ], "dataClassification": "confidential", "sensitiveFields": [ "body" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^commerce:order-confirmed:" } }, { "type": "commerce.order.ready", "version": 1, "description": "An order moved durably into the completed and ready terminal state before delivery.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "order_id", "previous_status", "status", "total_cents", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "order_id": { "type": "string", "minLength": 1 }, "previous_status": { "type": "string", "minLength": 1 }, "status": { "type": "string", "const": "completed" }, "total_cents": { "type": "integer", "minimum": 0 }, "surface": { "type": "string", "const": "notification" }, "priority": { "type": "string", "const": "high" }, "category": { "type": "string", "const": "commerce" }, "severity": { "type": "string", "const": "success" }, "object_type": { "type": "string", "const": "commerce_order" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Order ready", "body": "Guest order: Charred Corn Toast", "object_id": "order_1", "order_id": "order_1", "previous_status": "active", "status": "completed", "total_cents": 1200, "surface": "notification", "priority": "high", "category": "commerce", "severity": "success", "object_type": "commerce_order", "occurred_at": "2026-07-20T00:10:00.000Z", "cta_url": "https://commerce.topolo.app/venues/venue_1/queues" } ], "dataClassification": "confidential", "sensitiveFields": [ "body" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^commerce:order-ready:" } }, { "type": "commerce.order.cancelled", "version": 1, "description": "An order moved durably into the cancelled terminal state before delivery.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "order_id", "previous_status", "status", "total_cents", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "order_id": { "type": "string", "minLength": 1 }, "previous_status": { "type": "string", "minLength": 1 }, "status": { "type": "string", "const": "cancelled" }, "total_cents": { "type": "integer", "minimum": 0 }, "surface": { "type": "string", "const": "action" }, "action_kind": { "type": "string", "const": "review" }, "action_status": { "type": "string", "const": "open" }, "priority": { "type": "string", "const": "high" }, "category": { "type": "string", "const": "commerce" }, "severity": { "type": "string", "const": "warning" }, "object_type": { "type": "string", "const": "commerce_order" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Order cancelled", "body": "Guest order: Charred Corn Toast", "object_id": "order_2", "order_id": "order_2", "previous_status": "queued", "status": "cancelled", "total_cents": 1200, "surface": "action", "action_kind": "review", "action_status": "open", "priority": "high", "category": "commerce", "severity": "warning", "object_type": "commerce_order", "occurred_at": "2026-07-20T00:02:00.000Z", "cta_url": "https://commerce.topolo.app/venues/venue_1/queues" } ], "dataClassification": "confidential", "sensitiveFields": [ "body" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^commerce:order-cancelled:" } }, { "type": "commerce.service_request.created", "version": 1, "description": "A guest service request and its operations ticket were committed before venue-staff delivery.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "service_request_id", "status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "service_request_id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "const": "queued" }, "surface": { "type": "string", "const": "action" }, "action_kind": { "type": "string", "const": "complete" }, "action_status": { "type": "string", "const": "open" }, "priority": { "type": "string", "const": "high" }, "category": { "type": "string", "const": "commerce" }, "severity": { "type": "string", "const": "info" }, "object_type": { "type": "string", "const": "commerce_service_request" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "New service request", "body": "Need napkins", "object_id": "request_1", "service_request_id": "request_1", "status": "queued", "surface": "action", "action_kind": "complete", "action_status": "open", "priority": "high", "category": "commerce", "severity": "info", "object_type": "commerce_service_request", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://commerce.topolo.app/venues/venue_1/queues" } ], "dataClassification": "confidential", "sensitiveFields": [ "body" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^commerce:service-request-created:" } }, { "type": "commerce.service_request.status_changed", "version": 1, "description": "A service request changed durable workflow status before delivery.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "service_request_id", "previous_status", "status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "service_request_id": { "type": "string", "minLength": 1 }, "previous_status": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "surface": { "type": "string", "const": "notification" }, "priority": { "type": "string", "const": "normal" }, "category": { "type": "string", "const": "commerce" }, "severity": { "type": "string", "enum": [ "info", "success", "warning" ] }, "object_type": { "type": "string", "const": "commerce_service_request" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Service request updated", "body": "Need napkins", "object_id": "request_1", "service_request_id": "request_1", "previous_status": "queued", "status": "cancelled", "surface": "notification", "priority": "normal", "category": "commerce", "severity": "warning", "object_type": "commerce_service_request", "occurred_at": "2026-07-20T00:02:00.000Z", "cta_url": "https://commerce.topolo.app/venues/venue_1/queues" } ], "dataClassification": "confidential", "sensitiveFields": [ "body" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^commerce:service-request-status:" } } ] }, "actions": [ { "name": "organizations.data.export", "title": "Export organization data", "description": "Export organization-authored Commerce data and object metadata without credentials or binary payloads.", "method": "GET", "path": "/api/organizations/{organizationId}/data", "permission": "privacy:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "organizationId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/example/data", "body": null }, "effects": "Reads state through GET /api/organizations/{organizationId}/data without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.erase", "title": "Erase organization data", "description": "Erase organization-authored Commerce data, object storage, and live queue projections after literal ERASE confirmation.", "method": "DELETE", "path": "/api/organizations/{organizationId}/data", "permission": "privacy:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "organizationId", "confirmation" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "organizationId": "example", "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/example/data", "body": null }, "effects": "May change state through DELETE /api/organizations/{organizationId}/data. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "Delete workspace", "description": "Delete an empty non-default Commerce workspace.", "method": "DELETE", "path": "/api/workspaces/{workspaceId}", "permission": "workspace:delete", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "dashboard:read", "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-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "org.context.get", "title": "Get commerce context", "description": "Get commerce organization context.", "method": "GET", "path": "/api/org/context", "permission": "dashboard:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get commerce context.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/org/context", "body": null }, "effects": "Reads state through GET /api/org/context without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/org/context", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.list", "title": "List venues", "description": "List commerce venues.", "method": "GET", "path": "/api/venues", "permission": "venues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List venues.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues", "body": null }, "effects": "Reads state through GET /api/venues without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.create", "title": "Create venue", "description": "Create a commerce venue.", "method": "POST", "path": "/api/venues", "permission": "venues:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string" }, "presetKey": { "type": "string" }, "verticalPack": { "type": "string" }, "serviceModel": { "type": "string" }, "paymentMode": { "type": "string" }, "summary": { "type": "string" }, "experience": { "type": "object", "properties": {}, "additionalProperties": {} }, "moduleOverrides": { "type": "object", "properties": {}, "additionalProperties": {} }, "catalogSeed": { "type": "object", "properties": {}, "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "name", "clientMutationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create venue.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "name": "example", "clientMutationId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/venues", "body": { "name": "example", "clientMutationId": "example" } }, "effects": "May change state through POST /api/venues. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/venues", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.get", "title": "Get venue", "description": "Get one commerce venue.", "method": "GET", "path": "/api/venues/{venueId}", "permission": "venues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get venue.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example", "body": null }, "effects": "Reads state through GET /api/venues/{venueId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.update", "title": "Update venue", "description": "Update a Commerce venue.", "method": "PUT", "path": "/api/venues/{venueId}", "permission": "settings:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "presetKey": { "type": "string" }, "moduleSettings": { "type": "object", "properties": {}, "additionalProperties": {} }, "enabledModules": { "type": "array", "items": { "type": "string" } }, "disabledModules": { "type": "array", "items": { "type": "string" } }, "moduleOverrides": { "type": "object", "properties": {}, "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update venue.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/venues/example", "body": { "venueId": "example" } }, "effects": "May change state through PUT /api/venues/{venueId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/venues/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "devices.list", "title": "List venue devices", "description": "List devices for a venue.", "method": "GET", "path": "/api/venues/{venueId}/devices", "permission": "devices:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List venue devices.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/devices", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/devices without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/devices", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "orders.list", "title": "List orders", "description": "List commerce orders.", "method": "GET", "path": "/api/orders", "permission": "queues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List orders.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/orders", "body": null }, "effects": "Reads state through GET /api/orders without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/orders", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "orders.create", "title": "Create order", "description": "Create a commerce order.", "method": "POST", "path": "/api/orders", "authorizationMode": "public", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "lines": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string", "minLength": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "notes": { "type": "string" }, "selectedModifiers": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string", "minLength": 1 }, "optionIds": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "groupId" ], "additionalProperties": false } } }, "required": [ "itemId" ], "additionalProperties": false } }, "guestSessionId": { "type": "string" }, "tableTabMemberId": { "type": "string" }, "deviceToken": { "type": "string" }, "tableLabel": { "type": "string" }, "zoneLabel": { "type": "string" }, "note": { "type": "string" }, "source": { "type": "string" }, "draftOrderId": { "type": "string" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "lines" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create order.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "lines": [ { "itemId": "example" } ] }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/orders", "body": { "venueId": "example", "lines": [ { "itemId": "example" } ] } }, "effects": "May change state through POST /api/orders. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/orders", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "service_requests.list", "title": "List service requests", "description": "List commerce service requests.", "method": "GET", "path": "/api/service-requests", "authorizationMode": "public", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "guestSessionId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "guestSessionId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List service requests.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example", "guestSessionId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/service-requests", "body": null }, "effects": "Reads state through GET /api/service-requests without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/service-requests", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "service_requests.update", "title": "Update service request", "description": "Update one service request.", "method": "PATCH", "path": "/api/service-requests/{requestId}", "authorizationMode": "public", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "guestSessionId": { "type": "string", "minLength": 1 }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "requestId", "guestSessionId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update service request.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "requestId": "example", "guestSessionId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/service-requests/example", "body": { "requestId": "example", "guestSessionId": "example" } }, "effects": "May change state through PATCH /api/service-requests/{requestId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/service-requests/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "payment_sessions.create", "title": "Create payment session", "description": "Create a commerce payment session.", "method": "POST", "path": "/api/payment-sessions", "permission": "payments:create", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "orderId": { "type": "string" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create payment session.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/payment-sessions", "body": { "venueId": "example" } }, "effects": "May change state through POST /api/payment-sessions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/payment-sessions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "publishing.push", "title": "Push venue edge update", "description": "Push venue edge/runtime state.", "method": "POST", "path": "/api/venues/{venueId}/edge/push", "authorizationMode": "public", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "events": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "runtimeState": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "venueId", "events" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Push venue edge update.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "events": [ {} ] }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/venues/example/edge/push", "body": { "venueId": "example", "events": [ {} ] } }, "effects": "May change state through POST /api/venues/{venueId}/edge/push. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/venues/*/edge/push", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "org.module_settings.get", "title": "Get module settings", "description": "Get Commerce organization module settings.", "method": "GET", "path": "/api/org/module-settings", "permission": "settings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get module settings.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/org/module-settings", "body": null }, "effects": "Reads state through GET /api/org/module-settings without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/org/module-settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "org.module_settings.update", "title": "Update module settings", "description": "Update Commerce organization module settings.", "method": "PUT", "path": "/api/org/module-settings", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "presetKey": { "type": "string" }, "moduleSettings": { "type": "object", "properties": {}, "additionalProperties": {} }, "enabledModules": { "type": "array", "items": { "type": "string" } }, "disabledModules": { "type": "array", "items": { "type": "string" } }, "moduleOverrides": { "type": "object", "properties": {}, "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update module settings.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "presetKey": "example", "moduleSettings": {}, "enabledModules": [ "example" ] }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/org/module-settings", "body": { "presetKey": "example", "moduleSettings": {}, "enabledModules": [ "example" ] } }, "effects": "May change state through PUT /api/org/module-settings. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/org/module-settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "org.module_settings.resolve", "title": "Resolve module settings", "description": "Resolve Commerce module settings.", "method": "POST", "path": "/api/org/module-settings/resolve", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "presetKey": { "type": "string" }, "orgSettings": { "type": "object", "properties": {}, "additionalProperties": {} }, "venueOverrides": { "type": "object", "properties": {}, "additionalProperties": {} } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Resolve module settings.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "presetKey": "example", "orgSettings": {}, "venueOverrides": {} }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/org/module-settings/resolve", "body": { "presetKey": "example", "orgSettings": {}, "venueOverrides": {} } }, "effects": "May change state through POST /api/org/module-settings/resolve. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/org/module-settings/resolve", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "org.hub_tiles.update", "title": "Update hub tiles", "description": "Update Commerce organization hub tiles.", "method": "PUT", "path": "/api/org/hub-tiles", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tiles": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "clientMutationId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update hub tiles.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "tiles": [ {} ], "clientMutationId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/org/hub-tiles", "body": { "tiles": [ {} ], "clientMutationId": "example" } }, "effects": "May change state through PUT /api/org/hub-tiles. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/org/hub-tiles", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.experience.get", "title": "Get venue experience", "description": "Get Commerce venue experience settings.", "method": "GET", "path": "/api/venues/{venueId}/experience", "permission": "venues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get venue experience.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/experience", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/experience without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/experience", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.experience.update", "title": "Update venue experience", "description": "Update Commerce venue experience settings.", "method": "PUT", "path": "/api/venues/{venueId}/experience", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "presentationMode": { "type": "string" }, "fontPreset": { "type": "string" }, "menuCardStyle": { "type": "string" }, "serviceActionStyle": { "type": "string" }, "accentColor": { "type": "string" }, "currency": { "type": "string" }, "locale": { "type": "string" }, "brandSurface": { "type": "string" }, "logoUrl": { "type": "string" }, "orderIntentTimer": { "type": "object", "properties": {}, "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update venue experience.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/venues/example/experience", "body": { "venueId": "example" } }, "effects": "May change state through PUT /api/venues/{venueId}/experience. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/venues/*/experience", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.hub_tiles.update", "title": "Update venue hub tiles", "description": "Update Commerce venue hub tiles.", "method": "PUT", "path": "/api/venues/{venueId}/hub-tiles", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "tiles": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update venue hub tiles.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/venues/example/hub-tiles", "body": { "venueId": "example" } }, "effects": "May change state through PUT /api/venues/{venueId}/hub-tiles. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/venues/*/hub-tiles", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.catalog.get", "title": "Get venue catalog", "description": "Get a Commerce venue catalog.", "method": "GET", "path": "/api/venues/{venueId}/catalog", "authorizationMode": "public", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get venue catalog.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/catalog", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/catalog without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/catalog", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.catalog.update", "title": "Update venue catalog", "description": "Update a Commerce venue catalog.", "method": "PUT", "path": "/api/venues/{venueId}/catalog", "permission": "catalog:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "kind": { "type": "string" }, "sections": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "serviceActions": { "type": "array", "items": { "type": "string" } }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update venue catalog.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/venues/example/catalog", "body": { "venueId": "example" } }, "effects": "May change state through PUT /api/venues/{venueId}/catalog. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/venues/*/catalog", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.beverage_guide.get", "title": "Get beverage guide", "description": "Get Commerce venue beverage guide.", "method": "GET", "path": "/api/venues/{venueId}/beverage-guide", "authorizationMode": "public", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get beverage guide.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/beverage-guide", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/beverage-guide without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/beverage-guide", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.resilience_state.get", "title": "Get resilience state", "description": "Get Commerce venue resilience state.", "method": "GET", "path": "/api/venues/{venueId}/resilience/state", "permission": "venues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get resilience state.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/resilience/state", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/resilience/state without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/resilience/state", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.devices.link", "title": "Link venue device", "description": "Link a Commerce venue device.", "method": "POST", "path": "/api/venues/{venueId}/devices/link", "permission": "devices:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "mdmDeviceId": { "type": "string" }, "deviceId": { "type": "string" }, "commerceDeviceId": { "type": "string" }, "mdmLabel": { "type": "string" }, "label": { "type": "string" }, "roleKey": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "assignmentMode": { "type": "string" }, "assignedStaffId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deviceType": { "type": "string" }, "authPolicy": { "type": "string" }, "localIdentifier": { "type": "string" }, "mdmLastSeenAt": { "type": "number" }, "mdmManufacturer": { "type": "string" }, "mdmModel": { "type": "string" }, "mdmSerialNumber": { "type": "string" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "roleKey" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Link venue device.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "roleKey": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/venues/example/devices/link", "body": { "venueId": "example", "roleKey": "example" } }, "effects": "May change state through POST /api/venues/{venueId}/devices/link. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/venues/*/devices/link", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.devices.profile.update", "title": "Update venue device profile", "description": "Update a Commerce venue device profile.", "method": "PUT", "path": "/api/venues/{venueId}/devices/{deviceId}/profile", "permission": "devices:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "deviceId": { "type": "string", "minLength": 1 }, "profile": { "type": "object", "properties": {}, "additionalProperties": {} }, "mode": { "type": "string" }, "kioskState": { "type": "string" }, "policyPreset": { "type": "string" }, "launcherPackage": { "type": "string" }, "launcherTarget": { "type": "object", "properties": {}, "additionalProperties": {} }, "contentAssignment": { "type": "object", "properties": {}, "additionalProperties": {} }, "metadata": { "type": "object", "properties": {}, "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "deviceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update venue device profile.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "deviceId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/venues/example/devices/example/profile", "body": { "venueId": "example", "deviceId": "example" } }, "effects": "May change state through PUT /api/venues/{venueId}/devices/{deviceId}/profile. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/venues/*/devices/*/profile", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.devices.command.create", "title": "Create venue device command", "description": "Create a Commerce venue device command.", "method": "POST", "path": "/api/venues/{venueId}/devices/{deviceId}/command", "permission": "devices:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "deviceId": { "type": "string", "minLength": 1 }, "action": { "type": "string", "minLength": 1 }, "commandId": { "type": "string" }, "parameters": { "type": "object", "properties": {}, "additionalProperties": {} }, "packageName": { "type": "string" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "deviceId", "action" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create venue device command.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "deviceId": "example", "action": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/venues/example/devices/example/command", "body": { "venueId": "example", "deviceId": "example", "action": "example" } }, "effects": "May change state through POST /api/venues/{venueId}/devices/{deviceId}/command. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/venues/*/devices/*/command", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.payment_reconciliations.list", "title": "List payment reconciliations", "description": "List Commerce venue payment reconciliations.", "method": "GET", "path": "/api/venues/{venueId}/payment-reconciliations", "permission": "venues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List payment reconciliations.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/payment-reconciliations", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/payment-reconciliations without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/payment-reconciliations", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.payment_reconciliations.create", "title": "Create payment reconciliation", "description": "Create a Commerce venue payment reconciliation.", "method": "POST", "path": "/api/venues/{venueId}/payment-reconciliations", "permission": "payments:create", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "orderId": { "type": "string", "minLength": 1 }, "id": { "type": "string" }, "settlementKind": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "amountCents": { "type": "number" }, "externalReference": { "type": "string" }, "note": { "type": "string" }, "source": { "type": "string" }, "recordedAt": { "type": "number" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "orderId", "settlementKind" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create payment reconciliation.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "orderId": "example", "settlementKind": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/venues/example/payment-reconciliations", "body": { "venueId": "example", "orderId": "example", "settlementKind": "example" } }, "effects": "May change state through POST /api/venues/{venueId}/payment-reconciliations. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/venues/*/payment-reconciliations", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.sync_policy.get", "title": "Get sync policy", "description": "Get Commerce venue sync policy.", "method": "GET", "path": "/api/venues/{venueId}/sync-policy", "permission": "venues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get sync policy.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/sync-policy", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/sync-policy without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/sync-policy", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.sync_policy.update", "title": "Update sync policy", "description": "Update Commerce venue sync policy.", "method": "PUT", "path": "/api/venues/{venueId}/sync-policy", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "preferredSyncMode": { "type": "string" }, "rescueUplinkEnabled": { "type": "boolean" }, "rescueActivationAfterSeconds": { "type": "number" }, "unsyncedEventThreshold": { "type": "number" }, "maxRescueSessionMinutes": { "type": "number" }, "minPrimaryHealthySeconds": { "type": "number" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update sync policy.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/venues/example/sync-policy", "body": { "venueId": "example" } }, "effects": "May change state through PUT /api/venues/{venueId}/sync-policy. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/venues/*/sync-policy", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.staff_notifications.list", "title": "List staff notifications", "description": "List Commerce venue staff notifications.", "method": "GET", "path": "/api/venues/{venueId}/staff-notifications", "permission": "venues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "staffMemberId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List staff notifications.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/staff-notifications", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/staff-notifications without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/staff-notifications", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.staff_notifications.update", "title": "Update staff notification", "description": "Update a Commerce staff notification.", "method": "PUT", "path": "/api/venues/{venueId}/staff-notifications/{notificationId}", "permission": "queues:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "notificationId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed" ] }, "acceptedAt": { "type": "number" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "notificationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update staff notification.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "notificationId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/venues/example/staff-notifications/example", "body": { "venueId": "example", "notificationId": "example" } }, "effects": "May change state through PUT /api/venues/{venueId}/staff-notifications/{notificationId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/venues/*/staff-notifications/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.edge_nodes.list", "title": "List edge nodes", "description": "List Commerce venue edge nodes.", "method": "GET", "path": "/api/venues/{venueId}/edge/nodes", "permission": "venues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List edge nodes.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/edge/nodes", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/edge/nodes without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/edge/nodes", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.edge_nodes.create", "title": "Create edge node", "description": "Create a Commerce venue edge node.", "method": "POST", "path": "/api/venues/{venueId}/edge/nodes", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "nodeLabel": { "type": "string", "minLength": 1 }, "capabilities": { "type": "array", "items": { "type": "string" } }, "localEndpoint": { "type": "string" }, "notes": { "type": "string" }, "connectivityPolicy": { "type": "string" }, "metadata": { "type": "object", "properties": {}, "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "nodeLabel" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create edge node.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "nodeLabel": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/venues/example/edge/nodes", "body": { "venueId": "example", "nodeLabel": "example" } }, "effects": "May change state through POST /api/venues/{venueId}/edge/nodes. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/venues/*/edge/nodes", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.imports.list", "title": "List imports", "description": "List Commerce venue imports.", "method": "GET", "path": "/api/venues/{venueId}/imports", "permission": "imports:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List imports.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/imports", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/imports without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/imports", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.imports.create", "title": "Create import", "description": "Create a Commerce venue import.", "method": "POST", "path": "/api/venues/{venueId}/imports", "permission": "imports:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "sourceType": { "type": "string" }, "sourceName": { "type": "string" }, "notes": { "type": "string" }, "requestedVerticalPack": { "type": "string" }, "draftSummary": { "type": "string" }, "sourceFile": { "type": "object", "properties": { "dataUrl": { "type": "string", "minLength": 1 }, "filename": { "type": "string" }, "name": { "type": "string" } }, "required": [ "dataUrl" ], "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create import.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/venues/example/imports", "body": { "venueId": "example" } }, "effects": "May change state through POST /api/venues/{venueId}/imports. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/venues/*/imports", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.imports.approve", "title": "Approve import", "description": "Approve a Commerce venue import.", "method": "PUT", "path": "/api/venues/{venueId}/imports/{importId}/approve", "permission": "imports:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "importId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "importId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Approve import.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "importId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/venues/example/imports/example/approve", "body": { "venueId": "example", "importId": "example" } }, "effects": "May change state through PUT /api/venues/{venueId}/imports/{importId}/approve. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/venues/*/imports/*/approve", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.imports.reject", "title": "Reject import", "description": "Reject a Commerce venue import.", "method": "PUT", "path": "/api/venues/{venueId}/imports/{importId}/reject", "permission": "imports:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "importId": { "type": "string", "minLength": 1 }, "reason": { "type": "string" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "importId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Reject import.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "importId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/venues/example/imports/example/reject", "body": { "venueId": "example", "importId": "example" } }, "effects": "May change state through PUT /api/venues/{venueId}/imports/{importId}/reject. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/venues/*/imports/*/reject", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.imports.get", "title": "Get import", "description": "Get a Commerce venue import.", "method": "GET", "path": "/api/venues/{venueId}/imports/{importId}", "permission": "imports:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "importId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "importId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get import.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example", "importId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/imports/example", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/imports/{importId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/imports/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.imports.asset.get", "title": "Get import asset", "description": "Get a Commerce venue import asset.", "method": "GET", "path": "/api/venues/{venueId}/imports/{importId}/asset", "permission": "imports:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "importId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "importId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get import asset.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example", "importId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/imports/example/asset", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/imports/{importId}/asset without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/imports/*/asset", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.ops_voice.resolve", "title": "Resolve ops voice", "description": "Resolve Commerce ops voice input.", "method": "POST", "path": "/api/venues/{venueId}/ops/voice/resolve", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "transcript": { "type": "string" }, "utterance": { "type": "string" }, "audioDataUrl": { "type": "string" }, "mimeType": { "type": "string" }, "durationMs": { "type": "number" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Resolve ops voice.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/venues/example/ops/voice/resolve", "body": { "venueId": "example" } }, "effects": "May change state through POST /api/venues/{venueId}/ops/voice/resolve. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/venues/*/ops/voice/resolve", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.ops_tickets.list", "title": "List ops tickets", "description": "List Commerce venue ops tickets.", "method": "GET", "path": "/api/venues/{venueId}/ops/tickets", "permission": "queues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List ops tickets.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/ops/tickets", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/ops/tickets without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/ops/tickets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.ops_live_state.get", "title": "Get ops live state", "description": "Get Commerce venue ops live state.", "method": "GET", "path": "/api/venues/{venueId}/ops/live-state", "permission": "queues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get ops live state.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/ops/live-state", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/ops/live-state without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/ops/live-state", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.ops_live_stream_ticket.create", "title": "Create live stream ticket", "description": "Create a Commerce venue live stream ticket.", "method": "POST", "path": "/api/venues/{venueId}/ops/live-stream-ticket", "permission": "queues:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create live stream ticket.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/venues/example/ops/live-stream-ticket", "body": { "venueId": "example" } }, "effects": "May change state through POST /api/venues/{venueId}/ops/live-stream-ticket. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/venues/*/ops/live-stream-ticket", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.ops_tickets.update", "title": "Update ops ticket", "description": "Update a Commerce venue ops ticket.", "method": "PUT", "path": "/api/venues/{venueId}/ops/tickets/{ticketId}", "permission": "queues:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "ticketId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "active", "completed", "cancelled" ] }, "operatorNote": { "type": "string" }, "assignedStaffId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assignedSectionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expectedUpdatedAt": { "type": "number" }, "expectedStatus": { "type": "string" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "ticketId", "status" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update ops ticket.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "ticketId": "example", "status": "queued" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/venues/example/ops/tickets/example", "body": { "venueId": "example", "ticketId": "example", "status": "queued" } }, "effects": "May change state through PUT /api/venues/{venueId}/ops/tickets/{ticketId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/venues/*/ops/tickets/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.team.list", "title": "List team", "description": "List Commerce venue team members.", "method": "GET", "path": "/api/venues/{venueId}/team", "permission": "venues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List team.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/team", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/team without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/team", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.staff_identity_methods.list", "title": "List staff identity methods", "description": "List Commerce staff identity methods.", "method": "GET", "path": "/api/venues/{venueId}/staff-identity-methods", "permission": "venues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List staff identity methods.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/staff-identity-methods", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/staff-identity-methods without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/staff-identity-methods", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.team_sections.create", "title": "Create team section", "description": "Create a Commerce venue team section.", "method": "POST", "path": "/api/venues/{venueId}/team/sections", "permission": "venues:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "id": { "type": "string" }, "name": { "type": "string", "minLength": 1 }, "zoneLabel": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": "string" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create team section.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "name": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/venues/example/team/sections", "body": { "venueId": "example", "name": "example" } }, "effects": "May change state through POST /api/venues/{venueId}/team/sections. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/venues/*/team/sections", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.team_members.create", "title": "Create team member", "description": "Create a Commerce venue team member.", "method": "POST", "path": "/api/venues/{venueId}/team/members", "permission": "venues:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "id": { "type": "string" }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1 }, "roleKey": { "type": "string", "minLength": 1 }, "sectionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "deviceType": { "type": "string" }, "notificationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "displayName", "roleKey" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create team member.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "displayName": "example", "roleKey": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/venues/example/team/members", "body": { "venueId": "example", "displayName": "example", "roleKey": "example" } }, "effects": "May change state through POST /api/venues/{venueId}/team/members. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/venues/*/team/members", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.team_members.update", "title": "Update team member", "description": "Update a Commerce venue team member.", "method": "PUT", "path": "/api/venues/{venueId}/team/members/{memberId}", "permission": "venues:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "memberId": { "type": "string", "minLength": 1 }, "displayName": { "type": "string" }, "roleKey": { "type": "string" }, "sectionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "deviceType": { "type": "string" }, "notificationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "memberId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update team member.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "memberId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/venues/example/team/members/example", "body": { "venueId": "example", "memberId": "example" } }, "effects": "May change state through PUT /api/venues/{venueId}/team/members/{memberId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/venues/*/team/members/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.team_members.identity_methods.create", "title": "Create team member identity method", "description": "Create a Commerce team member identity method.", "method": "POST", "path": "/api/venues/{venueId}/team/members/{memberId}/identity-methods", "permission": "venues:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "memberId": { "type": "string", "minLength": 1 }, "id": { "type": "string" }, "methodType": { "type": "string", "minLength": 1 }, "credential": { "type": "string" }, "credentialHash": { "type": "string" }, "credentialSalt": { "type": "string" }, "credentialAlgorithm": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "mustChangeOnFirstUse": { "type": "boolean" }, "mustChangeOnNextUse": { "type": "boolean" }, "lastUsedAt": { "type": "number" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "memberId", "methodType" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create team member identity method.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "memberId": "example", "methodType": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/venues/example/team/members/example/identity-methods", "body": { "venueId": "example", "memberId": "example", "methodType": "example" } }, "effects": "May change state through POST /api/venues/{venueId}/team/members/{memberId}/identity-methods. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/venues/*/team/members/*/identity-methods", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.security_policy.get", "title": "Get security policy", "description": "Get Commerce venue security policy.", "method": "GET", "path": "/api/venues/{venueId}/security-policy", "permission": "settings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get security policy.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/security-policy", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/security-policy without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/security-policy", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.security_policy.update", "title": "Update security policy", "description": "Update Commerce venue security policy.", "method": "PATCH", "path": "/api/venues/{venueId}/security-policy", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "acceptedIdentityMethods": { "type": "array", "items": { "type": "string" } }, "pinLength": { "type": "number" }, "idleTimeoutSecondsByStationMode": { "type": "object", "properties": {}, "additionalProperties": {} }, "lockoutThresholdAttempts": { "type": "number" }, "lockoutWindowSeconds": { "type": "number" }, "lockoutDurationSeconds": { "type": "number" }, "discountStepUpThresholdCents": { "type": "number" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update security policy.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/venues/example/security-policy", "body": { "venueId": "example" } }, "effects": "May change state through PATCH /api/venues/{venueId}/security-policy. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/venues/*/security-policy", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.operator_access_snapshot.get", "title": "Get operator access snapshot", "description": "Get Commerce operator access snapshot.", "method": "GET", "path": "/api/venues/{venueId}/operator-access-snapshot", "permission": "settings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get operator access snapshot.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/operator-access-snapshot", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/operator-access-snapshot without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/operator-access-snapshot", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.action_permissions.list", "title": "List action permissions", "description": "List Commerce venue action permissions.", "method": "GET", "path": "/api/venues/{venueId}/action-permissions", "permission": "settings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List action permissions.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/action-permissions", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/action-permissions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/action-permissions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.action_permissions.update", "title": "Update action permission", "description": "Update Commerce venue action permission.", "method": "PUT", "path": "/api/venues/{venueId}/action-permissions/{actionKey}", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "actionKey": { "type": "string", "minLength": 1 }, "requiredRoleKeys": { "type": "array", "items": { "type": "string" } }, "stepUpRequired": { "type": "boolean" }, "payload": { "type": "object", "properties": {}, "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "actionKey" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update action permission.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "actionKey": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/venues/example/action-permissions/example", "body": { "venueId": "example", "actionKey": "example" } }, "effects": "May change state through PUT /api/venues/{venueId}/action-permissions/{actionKey}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/venues/*/action-permissions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.tables.floor_plan.get", "title": "Get floor plan", "description": "Get Commerce venue table floor plan.", "method": "GET", "path": "/api/venues/{venueId}/tables/floor-plan", "permission": "venues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get floor plan.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/tables/floor-plan", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/tables/floor-plan without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/tables/floor-plan", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.tables.floor_plan.update", "title": "Update floor plan", "description": "Update Commerce venue table floor plan.", "method": "PUT", "path": "/api/venues/{venueId}/tables/floor-plan", "permission": "venues:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "floorPlan": { "type": "object", "properties": { "gridCols": { "type": "number" }, "gridRows": { "type": "number" }, "tables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "shape": { "type": "string" }, "capacity": { "type": "number" }, "sectionLabel": { "type": "string" }, "zone": { "type": "string" } }, "additionalProperties": false } }, "version": { "type": "number" }, "updatedAt": { "type": "string" } }, "additionalProperties": false }, "gridCols": { "type": "number" }, "gridRows": { "type": "number" }, "tables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "shape": { "type": "string" }, "capacity": { "type": "number" }, "sectionLabel": { "type": "string" }, "zone": { "type": "string" } }, "additionalProperties": false } }, "ifVersion": { "type": "number" }, "version": { "type": "number" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update floor plan.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/venues/example/tables/floor-plan", "body": { "venueId": "example" } }, "effects": "May change state through PUT /api/venues/{venueId}/tables/floor-plan. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/venues/*/tables/floor-plan", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.tables.qr_summary.get", "title": "Get table QR summary", "description": "Get Commerce venue table QR summary.", "method": "GET", "path": "/api/venues/{venueId}/tables/qr-summary", "permission": "venues:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get table QR summary.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "venueId": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/venues/example/tables/qr-summary", "body": null }, "effects": "Reads state through GET /api/venues/{venueId}/tables/qr-summary without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/venues/*/tables/qr-summary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "venues.tables.sync_qr", "title": "Sync table QR", "description": "Sync Commerce venue table QR codes.", "method": "POST", "path": "/api/venues/{venueId}/tables/sync-qr", "permission": "venues:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "tables": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "number": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] }, "zone": { "type": "string" }, "sectionLabel": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "tables" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sync table QR.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "tables": [ { "id": "00000000-0000-4000-8000-000000000000" } ] }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/venues/example/tables/sync-qr", "body": { "venueId": "example", "tables": [ { "id": "00000000-0000-4000-8000-000000000000" } ] } }, "effects": "May change state through POST /api/venues/{venueId}/tables/sync-qr. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/venues/*/tables/sync-qr", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "assets.upload", "title": "Upload asset", "description": "Upload a Commerce admin asset.", "method": "PUT", "path": "/api/admin/upload-asset", "permission": "catalog:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string", "minLength": 1, "maxLength": 14000000 }, "contentType": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "image/gif" ] }, "fileName": { "type": "string", "minLength": 1 }, "assetKind": { "type": "string", "enum": [ "catalog-images", "voice-reviews" ] } }, "required": [ "venueId", "contentBase64", "contentType", "fileName" ], "additionalProperties": false }, "agentContract": { "upload": { "profile": "inline-base64", "contentField": "contentBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 10485760, "acceptedContentTypes": [ "image/png", "image/jpeg", "image/webp", "image/gif" ] } }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Upload asset.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "venueId": "example", "contentBase64": "example", "contentType": "image/png", "fileName": "example" }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/admin/upload-asset", "body": { "venueId": "example", "contentBase64": "example", "contentType": "image/png", "fileName": "example" } }, "effects": "May change state through PUT /api/admin/upload-asset. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/admin/upload-asset", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "catalog_images.generate", "title": "Generate catalog images", "description": "Generate Commerce catalog images.", "method": "POST", "path": "/api/admin/generate-catalog-images", "permission": "catalog:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "venueId": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "id", "venueId", "prompt" ], "additionalProperties": false } }, "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "items" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Generate catalog images.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "items": [ { "id": "00000000-0000-4000-8000-000000000000", "venueId": "example", "prompt": "example" } ] }, "cli_example": [ "topolo actions --service topolo-commerce --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/generate-catalog-images", "body": { "items": [ { "id": "00000000-0000-4000-8000-000000000000", "venueId": "example", "prompt": "example" } ] } }, "effects": "May change state through POST /api/admin/generate-catalog-images. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/generate-catalog-images", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 111, "matched_actions": 66, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 45, "configured_exclusions": 43, "configuration_findings": [], "notes": [ "no routes extracted from ops", "no routes extracted from station", "1 manually-declared route(s)" ] }, "runtime_contract_audit": { "status": "verified", "actions": 66, "contracts": 66, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/index.js" ], "authorization_sources": [ "apps/api/src/index.js" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloCommerce/topolo.mobile-experience.json", "contract": { "version": "2026-06-29", "status": "approved", "mode": "native_capability", "appId": "app_topolo_commerce", "localizationNamespace": "commerce", "permissions": [ "venues:read", "venues:write", "settings:write", "queues:read", "service-requests:read" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/venues", "auth": { "audience": "topolo-commerce", "scopes": [ "venues:read", "venues:write", "settings:write", "queues:read", "service-requests:read" ] }, "routes": [ { "path": "/venues", "apiPath": "/api/venues", "title": "Venues", "titleKey": "commerce.mobile.routes.venues.title", "template": "record.list", "dataSource": "commerce.venues.list", "detailRoute": "/venues/:id", "actions": [ { "id": "commerce.venues.create", "title": "Create venue", "type": "record.create", "permission": "venues:write", "method": "POST", "path": "/api/venues", "fields": [ { "key": "name", "label": "Name", "type": "text", "required": true }, { "key": "slug", "label": "Slug", "type": "text" }, { "key": "verticalPack", "label": "Vertical pack", "type": "text" }, { "key": "serviceModel", "label": "Service model", "type": "text" }, { "key": "paymentMode", "label": "Payment mode", "type": "text" }, { "key": "summary", "label": "Summary", "type": "textarea" }, { "key": "presetKey", "label": "Preset key", "type": "text" } ], "titleKey": "commerce.mobile.actions.venues.create.title" }, { "id": "commerce.venues.updateSettings", "title": "Update venue settings", "type": "record.update", "permission": "settings:write", "method": "PUT", "path": "/api/venues/:id", "fields": [ { "key": "name", "label": "Name", "type": "text", "required": true }, { "key": "slug", "label": "Slug", "type": "text" }, { "key": "verticalPack", "label": "Vertical pack", "type": "text" }, { "key": "serviceModel", "label": "Service model", "type": "text" }, { "key": "paymentMode", "label": "Payment mode", "type": "text" }, { "key": "summary", "label": "Summary", "type": "textarea" }, { "key": "presetKey", "label": "Preset key", "type": "text" } ], "titleKey": "commerce.mobile.actions.venues.update.settings.title" } ] }, { "path": "/venues/:id", "apiPath": "/api/venues/:id", "title": "Venue", "titleKey": "commerce.mobile.routes.venues.title", "template": "record.detail", "dataSource": "commerce.venues.detail" }, { "path": "/orders", "apiPath": "/api/orders", "title": "Orders", "titleKey": "commerce.mobile.routes.orders.title", "template": "record.list", "dataSource": "commerce.orders.list" }, { "path": "/service-requests", "apiPath": "/api/service-requests", "title": "Service requests", "titleKey": "commerce.mobile.routes.serviceRequests.title", "template": "record.list", "dataSource": "commerce.serviceRequests.list" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "LITERAL", "path": "/snapshot", "source_path": "apps/TopoloCommerce/apps/api/scripts/queue-stream-soak.mjs" }, { "method": "LITERAL", "path": "/snapshot", "source_path": "apps/TopoloCommerce/apps/api/scripts/queue-stress.mjs" }, { "method": "LITERAL", "path": "/bootstrap", "source_path": "apps/TopoloCommerce/apps/api/scripts/queue-stress.mjs" }, { "method": "LITERAL", "path": "/stream", "source_path": "apps/TopoloCommerce/apps/api/scripts/queue-stress.mjs" }, { "method": "GET", "path": "/api/assets/*", "source_path": "apps/TopoloCommerce/apps/api/src/assetRoutes.js" }, { "method": "PUT", "path": "/api/admin/upload-asset", "source_path": "apps/TopoloCommerce/apps/api/src/assetRoutes.js" }, { "method": "POST", "path": "/api/admin/generate-catalog-images", "source_path": "apps/TopoloCommerce/apps/api/src/assetRoutes.js" }, { "method": "POST", "path": "/api/guest/bill", "source_path": "apps/TopoloCommerce/apps/api/src/guestBillRoutes.js" }, { "method": "POST", "path": "/api/guest/bill/payments", "source_path": "apps/TopoloCommerce/apps/api/src/guestBillRoutes.js" }, { "method": "POST", "path": "/api/guest/bill/payment-link", "source_path": "apps/TopoloCommerce/apps/api/src/guestBillRoutes.js" }, { "method": "GET", "path": "/api/guest/bill/payment-link/:linkId", "source_path": "apps/TopoloCommerce/apps/api/src/guestBillRoutes.js" }, { "method": "GET", "path": "/api/guest/tab", "source_path": "apps/TopoloCommerce/apps/api/src/guestTableTabRoutes.js" }, { "method": "GET", "path": "/api/guest/table-tabs", "source_path": "apps/TopoloCommerce/apps/api/src/guestTableTabRoutes.js" }, { "method": "POST", "path": "/api/guest/table-tabs", "source_path": "apps/TopoloCommerce/apps/api/src/guestTableTabRoutes.js" }, { "method": "POST", "path": "/api/guest/table-tabs/join-requests", "source_path": "apps/TopoloCommerce/apps/api/src/guestTableTabRoutes.js" }, { "method": "GET", "path": "/api/guest/table-tabs/join-requests/:reqId", "source_path": "apps/TopoloCommerce/apps/api/src/guestTableTabRoutes.js" }, { "method": "GET", "path": "/api/guest/table-tabs/:tabId", "source_path": "apps/TopoloCommerce/apps/api/src/guestTableTabRoutes.js" }, { "method": "POST", "path": "/api/guest/table-tabs/:tabId/join-requests/:reqId/respond", "source_path": "apps/TopoloCommerce/apps/api/src/guestTableTabRoutes.js" }, { "method": "POST", "path": "/api/guest/table-tabs/:tabId/close", "source_path": "apps/TopoloCommerce/apps/api/src/guestTableTabRoutes.js" }, { "method": "POST", "path": "/api/guest/sessions", "source_path": "apps/TopoloCommerce/apps/api/src/guestTableTabRoutes.js" }, { "method": "ALL", "path": "/health", "source_path": "apps/TopoloCommerce/apps/api/src/index.js" }, { "method": "GET", "path": "/api/widget", "source_path": "apps/TopoloCommerce/apps/api/src/index.js" }, { "method": "GET", "path": "/api/guest/venues", "source_path": "apps/TopoloCommerce/apps/api/src/index.js" }, { "method": "GET", "path": "/api/guest/venues/:slug", "source_path": "apps/TopoloCommerce/apps/api/src/index.js" }, { "method": "POST", "path": "/api/orders", "source_path": "apps/TopoloCommerce/apps/api/src/index.js" }, { "method": "PUT", "path": "/api/draft-orders", "source_path": "apps/TopoloCommerce/apps/api/src/index.js" }, { "method": "POST", "path": "/api/service-requests", "source_path": "apps/TopoloCommerce/apps/api/src/index.js" }, { "method": "PATCH", "path": "/api/service-requests/:id", "source_path": "apps/TopoloCommerce/apps/api/src/index.js" }, { "method": "POST", "path": "/api/bookings", "source_path": "apps/TopoloCommerce/apps/api/src/index.js" }, { "method": "POST", "path": "/api/payment-sessions", "source_path": "apps/TopoloCommerce/apps/api/src/index.js" }, { "method": "GET", "path": "/api/orders", "source_path": "apps/TopoloCommerce/apps/api/src/operatorNativeRoutes.js" }, { "method": "GET", "path": "/api/service-requests", "source_path": "apps/TopoloCommerce/apps/api/src/operatorNativeRoutes.js" }, { "method": "GET", "path": "/security-policy", "source_path": "apps/TopoloCommerce/apps/api/src/routes/accessControl.js" }, { "method": "GET", "path": "/operator-access-snapshot", "source_path": "apps/TopoloCommerce/apps/api/src/routes/accessControl.js" }, { "method": "PATCH", "path": "/security-policy", "source_path": "apps/TopoloCommerce/apps/api/src/routes/accessControl.js" }, { "method": "GET", "path": "/action-permissions", "source_path": "apps/TopoloCommerce/apps/api/src/routes/accessControl.js" }, { "method": "PUT", "path": "/action-permissions/:actionKey", "source_path": "apps/TopoloCommerce/apps/api/src/routes/accessControl.js" }, { "method": "POST", "path": "/devices/:deviceId/operator-sessions", "source_path": "apps/TopoloCommerce/apps/api/src/routes/accessControl.js" }, { "method": "DELETE", "path": "/devices/:deviceId/operator-sessions/:sessionId", "source_path": "apps/TopoloCommerce/apps/api/src/routes/accessControl.js" }, { "method": "POST", "path": "/operator-sessions/:sessionId/step-up", "source_path": "apps/TopoloCommerce/apps/api/src/routes/accessControl.js" }, { "method": "POST", "path": "/operator-sessions/:sessionId/credential", "source_path": "apps/TopoloCommerce/apps/api/src/routes/accessControl.js" }, { "method": "POST", "path": "/devices/link", "source_path": "apps/TopoloCommerce/apps/api/src/routes/deviceMdm.js" }, { "method": "PUT", "path": "/devices/:deviceId/profile", "source_path": "apps/TopoloCommerce/apps/api/src/routes/deviceMdm.js" }, { "method": "POST", "path": "/devices/:deviceId/command", "source_path": "apps/TopoloCommerce/apps/api/src/routes/deviceMdm.js" }, { "method": "GET", "path": "/devices", "source_path": "apps/TopoloCommerce/apps/api/src/routes/deviceMdm.js" }, { "method": "GET", "path": "/imports", "source_path": "apps/TopoloCommerce/apps/api/src/routes/imports.js" }, { "method": "POST", "path": "/imports", "source_path": "apps/TopoloCommerce/apps/api/src/routes/imports.js" }, { "method": "PUT", "path": "/imports/:importId/approve", "source_path": "apps/TopoloCommerce/apps/api/src/routes/imports.js" }, { "method": "PUT", "path": "/imports/:importId/reject", "source_path": "apps/TopoloCommerce/apps/api/src/routes/imports.js" }, { "method": "GET", "path": "/imports/:importId", "source_path": "apps/TopoloCommerce/apps/api/src/routes/imports.js" }, { "method": "GET", "path": "/imports/:importId/asset", "source_path": "apps/TopoloCommerce/apps/api/src/routes/imports.js" }, { "method": "GET", "path": "/api/org/context", "source_path": "apps/TopoloCommerce/apps/api/src/routes/organization.js" }, { "method": "GET", "path": "/api/org/module-settings", "source_path": "apps/TopoloCommerce/apps/api/src/routes/organization.js" }, { "method": "PUT", "path": "/api/org/module-settings", "source_path": "apps/TopoloCommerce/apps/api/src/routes/organization.js" }, { "method": "POST", "path": "/api/org/module-settings/resolve", "source_path": "apps/TopoloCommerce/apps/api/src/routes/organization.js" }, { "method": "PUT", "path": "/api/org/hub-tiles", "source_path": "apps/TopoloCommerce/apps/api/src/routes/organization.js" }, { "method": "GET", "path": "/api/venues", "source_path": "apps/TopoloCommerce/apps/api/src/routes/organization.js" }, { "method": "POST", "path": "/api/venues", "source_path": "apps/TopoloCommerce/apps/api/src/routes/organization.js" }, { "method": "GET", "path": "/api/organizations/:organizationId/data", "source_path": "apps/TopoloCommerce/apps/api/src/routes/organizationData.js" }, { "method": "DELETE", "path": "/api/organizations/:organizationId/data", "source_path": "apps/TopoloCommerce/apps/api/src/routes/organizationData.js" }, { "method": "GET", "path": "/ops/tickets", "source_path": "apps/TopoloCommerce/apps/api/src/routes/queue.js" }, { "method": "GET", "path": "/ops/live-state", "source_path": "apps/TopoloCommerce/apps/api/src/routes/queue.js" }, { "method": "POST", "path": "/ops/live-stream-ticket", "source_path": "apps/TopoloCommerce/apps/api/src/routes/queue.js" }, { "method": "GET", "path": "/ops/live-stream", "source_path": "apps/TopoloCommerce/apps/api/src/routes/queue.js" }, { "method": "PUT", "path": "/ops/tickets/:ticketId", "source_path": "apps/TopoloCommerce/apps/api/src/routes/queue.js" }, { "method": "GET", "path": "/tables/floor-plan", "source_path": "apps/TopoloCommerce/apps/api/src/routes/tables.js" }, { "method": "PUT", "path": "/tables/floor-plan", "source_path": "apps/TopoloCommerce/apps/api/src/routes/tables.js" }, { "method": "GET", "path": "/tables/qr-summary", "source_path": "apps/TopoloCommerce/apps/api/src/routes/tables.js" }, { "method": "POST", "path": "/tables/sync-qr", "source_path": "apps/TopoloCommerce/apps/api/src/routes/tables.js" }, { "method": "GET", "path": "/team", "source_path": "apps/TopoloCommerce/apps/api/src/routes/team.js" }, { "method": "GET", "path": "/staff-identity-methods", "source_path": "apps/TopoloCommerce/apps/api/src/routes/team.js" }, { "method": "POST", "path": "/team/sections", "source_path": "apps/TopoloCommerce/apps/api/src/routes/team.js" }, { "method": "POST", "path": "/team/members", "source_path": "apps/TopoloCommerce/apps/api/src/routes/team.js" }, { "method": "POST", "path": "/team/members/:memberId/identity-methods", "source_path": "apps/TopoloCommerce/apps/api/src/routes/team.js" }, { "method": "PUT", "path": "/team/members/:memberId", "source_path": "apps/TopoloCommerce/apps/api/src/routes/team.js" }, { "method": "GET", "path": "/resilience/state", "source_path": "apps/TopoloCommerce/apps/api/src/routes/venueOperations.js" }, { "method": "GET", "path": "/payment-reconciliations", "source_path": "apps/TopoloCommerce/apps/api/src/routes/venueOperations.js" }, { "method": "POST", "path": "/payment-reconciliations", "source_path": "apps/TopoloCommerce/apps/api/src/routes/venueOperations.js" }, { "method": "GET", "path": "/sync-policy", "source_path": "apps/TopoloCommerce/apps/api/src/routes/venueOperations.js" }, { "method": "PUT", "path": "/sync-policy", "source_path": "apps/TopoloCommerce/apps/api/src/routes/venueOperations.js" }, { "method": "GET", "path": "/staff-notifications", "source_path": "apps/TopoloCommerce/apps/api/src/routes/venueOperations.js" }, { "method": "PUT", "path": "/staff-notifications/:notificationId", "source_path": "apps/TopoloCommerce/apps/api/src/routes/venueOperations.js" }, { "method": "GET", "path": "/edge/nodes", "source_path": "apps/TopoloCommerce/apps/api/src/routes/venueOperations.js" }, { "method": "POST", "path": "/edge/nodes", "source_path": "apps/TopoloCommerce/apps/api/src/routes/venueOperations.js" }, { "method": "POST", "path": "/edge/bootstrap", "source_path": "apps/TopoloCommerce/apps/api/src/routes/venueOperations.js" }, { "method": "POST", "path": "/edge/push", "source_path": "apps/TopoloCommerce/apps/api/src/routes/venueOperations.js" }, { "method": "GET", "path": "/edge/events", "source_path": "apps/TopoloCommerce/apps/api/src/routes/venueOperations.js" }, { "method": "POST", "path": "/edge/ack", "source_path": "apps/TopoloCommerce/apps/api/src/routes/venueOperations.js" }, { "method": "POST", "path": "/api/internal/workspaces/:workspaceId/renamed", "source_path": "apps/TopoloCommerce/apps/api/src/routes/workspaces.js" }, { "method": "DELETE", "path": "/api/workspaces/:workspaceId", "source_path": "apps/TopoloCommerce/apps/api/src/routes/workspaces.js" }, { "method": "LITERAL", "path": "/privacy/erase", "source_path": "apps/TopoloCommerce/apps/api/src/venueQueueCoordinator.js" }, { "method": "LITERAL", "path": "/snapshot", "source_path": "apps/TopoloCommerce/apps/api/src/venueQueueCoordinator.js" }, { "method": "LITERAL", "path": "/bootstrap", "source_path": "apps/TopoloCommerce/apps/api/src/venueQueueCoordinator.js" }, { "method": "LITERAL", "path": "/draft-orders", "source_path": "apps/TopoloCommerce/apps/api/src/venueQueueCoordinator.js" }, { "method": "LITERAL", "path": "/stream-tickets", "source_path": "apps/TopoloCommerce/apps/api/src/venueQueueCoordinator.js" }, { "method": "LITERAL", "path": "/stream", "source_path": "apps/TopoloCommerce/apps/api/src/venueQueueCoordinator.js" }, { "method": "GET", "path": "/api/voice/review-assets/*", "source_path": "apps/TopoloCommerce/apps/api/src/voiceRoutes.js" }, { "method": "POST", "path": "/api/voice/review-assets", "source_path": "apps/TopoloCommerce/apps/api/src/voiceRoutes.js" }, { "method": "POST", "path": "/api/voice/resolve", "source_path": "apps/TopoloCommerce/apps/api/src/voiceRoutes.js" }, { "method": "POST", "path": "/api/voice/translate", "source_path": "apps/TopoloCommerce/apps/api/src/voiceRoutes.js" } ], "ui_routes": [ { "path": "/${path}", "source_path": "apps/TopoloCommerce/apps/api/src/mdm.js" }, { "path": "/", "source_path": "apps/TopoloCommerce/apps/guest/src/App.jsx" }, { "path": "/pay/:linkId", "source_path": "apps/TopoloCommerce/apps/guest/src/App.jsx" }, { "path": "/__preview/experience", "source_path": "apps/TopoloCommerce/apps/guest/src/App.jsx" }, { "path": "/:venueSlug", "source_path": "apps/TopoloCommerce/apps/guest/src/App.jsx" }, { "path": "/dashboard", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/venues/:venueId", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/venues/:venueId/tables/print", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/venues/:venueId/:routeKey", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/catalog", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/imports", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/queues", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/resilience", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/team", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/hospitality", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/retail", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/service", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/devices", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/tables", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/settings", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/getting-started", "source_path": "apps/TopoloCommerce/apps/ops/src/App.jsx" }, { "path": "/launcher", "source_path": "apps/TopoloCommerce/apps/station/src/App.jsx" }, { "path": "/kitchen/:venueId", "source_path": "apps/TopoloCommerce/apps/station/src/App.jsx" }, { "path": "/pos/:venueId", "source_path": "apps/TopoloCommerce/apps/station/src/App.jsx" }, { "path": "/bar/:venueId", "source_path": "apps/TopoloCommerce/apps/station/src/App.jsx" }, { "path": "/expo/:venueId", "source_path": "apps/TopoloCommerce/apps/station/src/App.jsx" }, { "path": "/pair/:mode/:venueId", "source_path": "apps/TopoloCommerce/apps/station/src/App.jsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "internal/apps/commerce", "applications/commerce", "internal/apps/commerce-design", "internal/apps/commerce-modules", "internal/apps/commerce-resilience" ], "present_paths": [ "internal/apps/commerce", "applications/commerce", "internal/apps/commerce-design", "internal/apps/commerce-modules", "internal/apps/commerce-resilience" ], "missing_paths": [], "human_reference": "/systems/topolo-commerce", "machine_reference": "/machine/systems/topolo-commerce.json", "action_examples": 66, "action_schemas": 66 }, "source_findings": [] }, "topolo-crm": { "id": "topolo-crm", "name": "TopoloCRM", "slug": "topolo-crm", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloCRM" ], "source_revisions": [ { "source_path": "apps/TopoloCRM", "repository": "apps/TopoloCRM", "revision": "7b79b9768344e095e72f71c7f6d1a8dad22a156e", "ref": "origin/staging" } ], "source_counts": { "source_files": 217, "test_files": 133, "test_cases": 0, "migration_files": 0, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 134, "mobile_contracts": 1, "notifications": 9, "package_manifests": 3, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloCRM/topolo.app.json", "service_slug": "topolo-crm", "name": "topolo-crm", "app_id": "app_topolo_crm", "compatibility_date": "2026-04-10", "primary_target": null, "environments": [ "production", "staging" ], "targets": [ { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-crm-app", "subdomain": "crm", "healthcheck_path": null, "variable_names": [ "AUTH_API_URL", "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null } ] }, { "name": "api", "kind": "worker", "directory": "apps/api", "main": "index.ts", "worker_name": "topolo-crm-api", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "account_id", "API_KEY_HASH_ITERATIONS", "API_KEY_PREFIX", "CRM_PUBLIC_BASE_URL", "ENVIRONMENT", "NEXUS_GATEWAY_URL", "NODE_ENV", "SALT_ROUNDS", "TOPOLO_AUTH_URL", "TOPOLO_NOTIFY_URL", "TOPOLO_SEED_APP_ID" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "CRM_CONTROL_DB", "target": null }, { "kind": "d1", "binding": "CRM_DIRECTORY_DB", "target": null }, { "kind": "d1", "binding": "CRM_PIPELINE_DB", "target": null }, { "kind": "d1", "binding": "CRM_REAL_ESTATE_DB", "target": null }, { "kind": "d1", "binding": "CRM_PORTAL_DB", "target": null }, { "kind": "d1", "binding": "CRM_AUDIT_DB", "target": null }, { "kind": "r2", "binding": "crm_attachments", "target": null }, { "kind": "kv", "binding": "CRM_KV", "target": null } ] } ], "notifications": [ "crm.deal.stage_changed", "crm.lead.assigned", "crm.offer.received", "crm.offer.status_changed", "crm.portal_sync.failed", "crm.showing.scheduled", "crm.task.assigned", "crm.task.due", "crm.transaction.milestone_due" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_crm", "events": [ { "type": "crm.deal.stage_changed", "version": 1, "description": "A deal moved between pipeline stages.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "thread_key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "A deal moved between pipeline stages.", "body": "Open the owning app to review this event.", "object_id": "object_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^crm:deal-stage:" }, "sensitiveFields": [] }, { "type": "crm.lead.assigned", "version": 1, "description": "CRM recorded the durable lead assigned transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "category", "severity", "object_type", "object_id", "occurred_at", "thread_key" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "high" }, "category": { "const": "crm" }, "severity": { "const": "info" }, "object_type": { "const": "lead" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "previous_status": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "due_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "New lead assigned: Ada Lovelace", "body": "A portal lead was assigned to you in CRM.", "object_id": "lead_123", "thread_key": "crm:lead:lead_123", "surface": "notification", "priority": "high", "category": "crm", "severity": "info", "object_type": "lead", "occurred_at": "2026-07-22T00:00:00.000Z", "cta_url": "https://crm.stg.topolo.us/leads/lead_123", "cta_label": "Open in CRM" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^crm:lead-assigned:" } }, { "type": "crm.offer.received", "version": 1, "description": "CRM recorded the durable offer received transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "category", "severity", "object_type", "object_id", "occurred_at", "thread_key", "status" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "high" }, "category": { "const": "crm" }, "severity": { "const": "info" }, "object_type": { "const": "offer" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "previous_status": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "due_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Offer received: Northstar", "body": "A USD offer was recorded for review.", "object_id": "offer_123", "thread_key": "crm:offer:offer_123", "status": "draft", "surface": "notification", "priority": "high", "category": "crm", "severity": "info", "object_type": "offer", "occurred_at": "2026-07-22T00:00:00.000Z", "cta_url": "https://crm.stg.topolo.us/offers/offer_123", "cta_label": "Open in CRM" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^crm:offer-received:" } }, { "type": "crm.offer.status_changed", "version": 1, "description": "CRM recorded the durable offer status changed transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "category", "severity", "object_type", "object_id", "occurred_at", "thread_key", "previous_status", "status" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "category": { "const": "crm" }, "severity": { "const": "info" }, "object_type": { "const": "offer" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "previous_status": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "due_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Offer status changed to accepted", "body": "Northstar moved from pending to accepted.", "object_id": "offer_123", "thread_key": "crm:offer:offer_123", "previous_status": "pending", "status": "accepted", "surface": "notification", "priority": "normal", "category": "crm", "severity": "info", "object_type": "offer", "occurred_at": "2026-07-22T00:00:00.000Z", "cta_url": "https://crm.stg.topolo.us/offers/offer_123", "cta_label": "Open in CRM" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^crm:offer-status:" } }, { "type": "crm.portal_sync.failed", "version": 1, "description": "CRM recorded the durable portal sync failed transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "category", "severity", "object_type", "object_id", "occurred_at", "thread_key" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "high" }, "category": { "const": "crm" }, "severity": { "const": "critical" }, "object_type": { "const": "portal_sync" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "previous_status": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "due_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Portal sync failed: Northstar", "body": "The portal rejected the listing sync.", "object_id": "sync_123", "thread_key": "crm:listing:listing_123", "surface": "notification", "priority": "high", "category": "crm", "severity": "critical", "object_type": "portal_sync", "occurred_at": "2026-07-22T00:00:00.000Z", "cta_url": "https://crm.stg.topolo.us/portal-syncs/sync_123", "cta_label": "Open in CRM" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^crm:portal-sync-failed:" } }, { "type": "crm.showing.scheduled", "version": 1, "description": "CRM recorded the durable showing scheduled transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "category", "severity", "object_type", "object_id", "occurred_at", "thread_key", "due_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "category": { "const": "crm" }, "severity": { "const": "info" }, "object_type": { "const": "showing" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "previous_status": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "due_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Showing scheduled: Northstar", "body": "A property showing was scheduled.", "object_id": "showing_123", "thread_key": "crm:showing:showing_123", "due_at": "2026-07-23T10:00:00.000Z", "surface": "notification", "priority": "normal", "category": "crm", "severity": "info", "object_type": "showing", "occurred_at": "2026-07-22T00:00:00.000Z", "cta_url": "https://crm.stg.topolo.us/showings/showing_123", "cta_label": "Open in CRM" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^crm:showing-scheduled:" } }, { "type": "crm.task.assigned", "version": 1, "description": "CRM recorded the durable task assigned transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "category", "severity", "object_type", "object_id", "occurred_at", "thread_key" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "category": { "const": "crm" }, "severity": { "const": "info" }, "object_type": { "const": "task" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "previous_status": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "due_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Task assigned: Follow up", "body": "A CRM task was assigned to you.", "object_id": "task_123", "thread_key": "crm:task:task_123", "surface": "notification", "priority": "normal", "category": "crm", "severity": "info", "object_type": "task", "occurred_at": "2026-07-22T00:00:00.000Z", "cta_url": "https://crm.stg.topolo.us/tasks/task_123", "cta_label": "Open in CRM" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^crm:task-assigned:" } }, { "type": "crm.task.due", "version": 1, "description": "CRM recorded the durable task due transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "category", "severity", "object_type", "object_id", "occurred_at", "thread_key", "due_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "high" }, "category": { "const": "crm" }, "severity": { "const": "warning" }, "object_type": { "const": "task" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "previous_status": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "due_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Task due: Follow up", "body": "A CRM task assigned to you is due.", "object_id": "task_123", "thread_key": "crm:task:task_123", "due_at": "2026-07-23T10:00:00.000Z", "surface": "notification", "priority": "high", "category": "crm", "severity": "warning", "object_type": "task", "occurred_at": "2026-07-22T00:00:00.000Z", "cta_url": "https://crm.stg.topolo.us/tasks/task_123", "cta_label": "Open in CRM" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^crm:task-due:" } }, { "type": "crm.transaction.milestone_due", "version": 1, "description": "CRM recorded the durable transaction milestone due transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "category", "severity", "object_type", "object_id", "occurred_at", "thread_key", "due_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "high" }, "category": { "const": "crm" }, "severity": { "const": "warning" }, "object_type": { "const": "transaction_milestone" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "thread_key": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "previous_status": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "due_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Milestone due: Exchange", "body": "A transaction milestone assigned to your team is due.", "object_id": "milestone_123", "thread_key": "crm:transaction:transaction_123", "due_at": "2026-07-23T10:00:00.000Z", "surface": "notification", "priority": "high", "category": "crm", "severity": "warning", "object_type": "transaction_milestone", "occurred_at": "2026-07-22T00:00:00.000Z", "cta_url": "https://crm.stg.topolo.us/transaction-milestones/milestone_123", "cta_label": "Open in CRM" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^crm:milestone-due:" } } ] }, "actions": [ { "name": "contacts.list", "title": "List contacts", "description": "List contacts.", "target": "api", "method": "GET", "path": "/api/contacts", "permission": "contacts:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "type": "string" }, "company": { "type": "string" }, "company_id": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "sort_by": { "type": "string" }, "sort_order": { "type": "string" }, "job_title": { "type": "string" }, "employment_role": { "type": "string" }, "seniority": { "type": "string" }, "lead_status": { "type": "string" }, "lifecycle_stage": { "type": "string" }, "lead_score_min": { "type": "number" }, "lead_score_max": { "type": "number" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "has_email": { "type": "boolean" }, "has_phone": { "type": "boolean" }, "has_mobile_phone": { "type": "boolean" }, "created_after": { "type": "string" }, "created_before": { "type": "string" }, "updated_after": { "type": "string" }, "updated_before": { "type": "string" }, "tags": { "type": "string" } }, "additionalProperties": false }, "readOnly": true, "outputSchema": { "type": "object", "description": "Response returned by List contacts.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "q": "example", "company": "example", "company_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/contacts", "body": null }, "effects": "Reads state through GET /api/contacts without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/contacts", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "contacts.get", "title": "Get contacts", "description": "Get one contacts record.", "target": "api", "method": "GET", "path": "/api/contacts/{id}", "permission": "contacts:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "readOnly": true, "outputSchema": { "type": "object", "description": "Response returned by Get contacts.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/contacts/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/contacts/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/contacts/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "contacts.create", "title": "Create contacts", "description": "Create contacts.", "target": "api", "method": "POST", "path": "/api/contacts", "permission": "contacts:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "first": { "type": "string" }, "middle_name": { "type": "string" }, "last": { "type": "string" }, "salutation": { "type": "string" }, "suffix": { "type": "string" }, "email": { "type": "string" }, "stageId": { "type": "string" }, "phone": { "type": "string" }, "mobile_phone": { "type": "string" }, "company": { "type": "string" }, "company_id": { "type": "string" }, "tags": { "type": "string" }, "external_id": { "type": "string" }, "external_profile_url": { "type": "string" }, "instagram_url": { "type": "string" }, "tiktok_url": { "type": "string" }, "youtube_url": { "type": "string" }, "x_url": { "type": "string" }, "github_url": { "type": "string" }, "job_title": { "type": "string" }, "employment_role": { "type": "string" }, "seniority": { "type": "string" }, "department": { "type": "string" }, "lead_status": { "type": "string" }, "lifecycle_stage": { "type": "string" }, "contact_accuracy_grade": { "type": "string" }, "education_level": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postal_code": { "type": "string" }, "address": { "type": "string" }, "linkedin_url": { "type": "string" }, "website_url": { "type": "string" }, "audience_primary_platform": { "type": "string" }, "audience_primary_url": { "type": "string" }, "audience_primary_handle": { "type": "string" }, "audience_follower_count_last_updated": { "type": "string" }, "audience_niche": { "type": "string" }, "company_domain": { "type": "string" }, "company_size": { "type": "string" }, "linkedin_headline": { "type": "string" }, "linkedin_about": { "type": "string" }, "linkedin_recent_experience": { "type": "string" }, "linkedin_inferred_timezone": { "type": "string" }, "linkedin_captured_at": { "type": "string" }, "latest_traffic_source": { "type": "string" }, "original_traffic_source": { "type": "string" }, "first_touch_campaign": { "type": "string" }, "last_touch_campaign": { "type": "string" }, "contact_owner": { "type": "string" }, "hubspot_team": { "type": "string" }, "traffic_source_date": { "type": "string" }, "original_traffic_drill_down_1": { "type": "string" }, "original_traffic_drill_down_2": { "type": "string" }, "latest_traffic_drill_down_1": { "type": "string" }, "latest_traffic_drill_down_2": { "type": "string" }, "lead_score": { "type": "number" }, "audience_follower_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "linkedin_followers": { "type": "number" }, "linkedin_connections": { "type": "number" }, "social_profiles": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "url": { "type": "string" }, "handle": { "type": "string" }, "follower_count": { "type": "number" }, "follower_count_last_updated": { "type": "string" }, "is_primary": { "type": "boolean" } }, "required": [ "platform", "url" ], "additionalProperties": false } }, { "type": "null" } ] } }, "additionalProperties": false }, "requiresConfirmation": true, "outputSchema": { "type": "object", "description": "Response returned by Create contacts.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "first": "example", "middle_name": "example", "last": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/contacts", "body": { "first": "example", "middle_name": "example", "last": "example" } }, "effects": "May change state through POST /api/contacts. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/contacts", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "contacts.update", "title": "Update contacts", "description": "Update one contacts record.", "target": "api", "method": "PUT", "path": "/api/contacts/{id}", "permission": "contacts:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "first": { "type": "string" }, "middle_name": { "type": "string" }, "last": { "type": "string" }, "salutation": { "type": "string" }, "suffix": { "type": "string" }, "email": { "type": "string" }, "stageId": { "type": "string" }, "phone": { "type": "string" }, "mobile_phone": { "type": "string" }, "company": { "type": "string" }, "company_id": { "type": "string" }, "tags": { "type": "string" }, "external_id": { "type": "string" }, "external_profile_url": { "type": "string" }, "instagram_url": { "type": "string" }, "tiktok_url": { "type": "string" }, "youtube_url": { "type": "string" }, "x_url": { "type": "string" }, "github_url": { "type": "string" }, "job_title": { "type": "string" }, "employment_role": { "type": "string" }, "seniority": { "type": "string" }, "department": { "type": "string" }, "lead_status": { "type": "string" }, "lifecycle_stage": { "type": "string" }, "contact_accuracy_grade": { "type": "string" }, "education_level": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postal_code": { "type": "string" }, "address": { "type": "string" }, "linkedin_url": { "type": "string" }, "website_url": { "type": "string" }, "audience_primary_platform": { "type": "string" }, "audience_primary_url": { "type": "string" }, "audience_primary_handle": { "type": "string" }, "audience_follower_count_last_updated": { "type": "string" }, "audience_niche": { "type": "string" }, "company_domain": { "type": "string" }, "company_size": { "type": "string" }, "linkedin_headline": { "type": "string" }, "linkedin_about": { "type": "string" }, "linkedin_recent_experience": { "type": "string" }, "linkedin_inferred_timezone": { "type": "string" }, "linkedin_captured_at": { "type": "string" }, "latest_traffic_source": { "type": "string" }, "original_traffic_source": { "type": "string" }, "first_touch_campaign": { "type": "string" }, "last_touch_campaign": { "type": "string" }, "contact_owner": { "type": "string" }, "hubspot_team": { "type": "string" }, "traffic_source_date": { "type": "string" }, "original_traffic_drill_down_1": { "type": "string" }, "original_traffic_drill_down_2": { "type": "string" }, "latest_traffic_drill_down_1": { "type": "string" }, "latest_traffic_drill_down_2": { "type": "string" }, "lead_score": { "type": "number" }, "audience_follower_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "linkedin_followers": { "type": "number" }, "linkedin_connections": { "type": "number" }, "social_profiles": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "url": { "type": "string" }, "handle": { "type": "string" }, "follower_count": { "type": "number" }, "follower_count_last_updated": { "type": "string" }, "is_primary": { "type": "boolean" } }, "required": [ "platform", "url" ], "additionalProperties": false } }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "requiresConfirmation": true, "outputSchema": { "type": "object", "description": "Response returned by Update contacts.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/contacts/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/contacts/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/contacts/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "contacts.delete", "title": "Delete contacts", "description": "Delete one contacts record.", "target": "api", "method": "DELETE", "path": "/api/contacts/{id}", "permission": "contacts:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "destructive": true, "requiresConfirmation": true, "outputSchema": { "type": "object", "description": "Response returned by Delete contacts.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/contacts/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/contacts/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/contacts/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "companies.list", "title": "List companies", "description": "List companies.", "method": "GET", "path": "/api/companies", "permission": "companies:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List companies.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "search": "example", "page": 1, "limit": 1 }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/companies", "body": null }, "effects": "Reads state through GET /api/companies without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/companies", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "companies.create", "title": "Create companies", "description": "Create companies.", "method": "POST", "path": "/api/companies", "permission": "companies:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "website": { "type": "string" }, "domain": { "type": "string" }, "phone": { "type": "string" }, "fax": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "industry": { "type": "string" }, "employee_range": { "type": "string" }, "revenue_range": { "type": "string" }, "primary_sub_industry": { "type": "string" }, "linkedin_url": { "type": "string" }, "external_id": { "type": "string" }, "external_profile_url": { "type": "string" }, "logo_url": { "type": "string" }, "ticker": { "type": "string" }, "size": { "type": "string" }, "founded_year": { "type": "number" }, "employee_count": { "type": "number" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create companies.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "name": "example", "description": "example", "website": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/companies", "body": { "name": "example", "description": "example", "website": "example" } }, "effects": "May change state through POST /api/companies. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/companies", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "companies.get", "title": "Get companies", "description": "Get one companies record.", "method": "GET", "path": "/api/companies/{id}", "permission": "companies:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get companies.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/companies/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/companies/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/companies/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "companies.update", "title": "Update companies", "description": "Update one companies record.", "method": "PUT", "path": "/api/companies/{id}", "permission": "companies:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "website": { "type": "string" }, "domain": { "type": "string" }, "phone": { "type": "string" }, "fax": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "industry": { "type": "string" }, "employee_range": { "type": "string" }, "revenue_range": { "type": "string" }, "primary_sub_industry": { "type": "string" }, "linkedin_url": { "type": "string" }, "external_id": { "type": "string" }, "external_profile_url": { "type": "string" }, "logo_url": { "type": "string" }, "ticker": { "type": "string" }, "size": { "type": "string" }, "founded_year": { "type": "number" }, "employee_count": { "type": "number" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update companies.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/companies/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/companies/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/companies/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "companies.delete", "title": "Delete companies", "description": "Delete one companies record.", "method": "DELETE", "path": "/api/companies/{id}", "permission": "companies:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete companies.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/companies/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/companies/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/companies/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "deals.list", "title": "List deals", "description": "List deals.", "method": "GET", "path": "/api/deals", "permission": "deals:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "search": { "type": "string" }, "stage_id": { "type": "string" }, "pipeline_id": { "type": "string" }, "owner_id": { "type": "string" }, "company_id": { "type": "string" }, "contact_id": { "type": "string" }, "min_amount": { "type": "number" }, "max_amount": { "type": "number" }, "currency": { "type": "string" }, "min_probability": { "type": "number" }, "max_probability": { "type": "number" }, "expected_close_after": { "type": "string" }, "expected_close_before": { "type": "string" }, "created_after": { "type": "string" }, "created_before": { "type": "string" }, "updated_after": { "type": "string" }, "updated_before": { "type": "string" }, "sort_by": { "type": "string" }, "sort_order": { "type": "string" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List deals.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "page": 1, "limit": 1, "search": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/deals", "body": null }, "effects": "Reads state through GET /api/deals without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/deals", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "deals.create", "title": "Create deals", "description": "Create deals.", "method": "POST", "path": "/api/deals", "permission": "deals:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "owner_id": { "type": "string" }, "company_id": { "type": "string" }, "contact_id": { "type": "string" }, "currency": { "type": "string" }, "pipeline_id": { "type": "string" }, "stage_id": { "type": "string" }, "expected_close_date": { "type": "string" }, "amount_cents": { "type": "number" }, "amount": { "type": "number" }, "probability": { "type": "number" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create deals.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "name": "example", "description": "example", "owner_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/deals", "body": { "name": "example", "description": "example", "owner_id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/deals. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/deals", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "deals.get", "title": "Get deals", "description": "Get one deals record.", "method": "GET", "path": "/api/deals/{id}", "permission": "deals:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get deals.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/deals/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/deals/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/deals/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "deals.update", "title": "Update deals", "description": "Update one deals record.", "method": "PUT", "path": "/api/deals/{id}", "permission": "deals:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "owner_id": { "type": "string" }, "company_id": { "type": "string" }, "contact_id": { "type": "string" }, "currency": { "type": "string" }, "pipeline_id": { "type": "string" }, "stage_id": { "type": "string" }, "expected_close_date": { "type": "string" }, "amount_cents": { "type": "number" }, "amount": { "type": "number" }, "probability": { "type": "number" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update deals.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/deals/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/deals/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/deals/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "deals.delete", "title": "Delete deals", "description": "Delete one deals record.", "method": "DELETE", "path": "/api/deals/{id}", "permission": "deals:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete deals.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/deals/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/deals/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/deals/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "deals.stage.update", "title": "Update deal stage", "description": "Update a CRM deal stage.", "method": "PUT", "path": "/api/deals/{id}/stage", "permission": "deals:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "stageId": { "type": "string", "minLength": 1 } }, "required": [ "id", "stageId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update deal stage.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "stageId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/deals/00000000-0000-4000-8000-000000000000/stage", "body": { "id": "00000000-0000-4000-8000-000000000000", "stageId": "example" } }, "effects": "May change state through PUT /api/deals/{id}/stage. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/deals/*/stage", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "deals.history.get", "title": "Get deal history", "description": "Get CRM deal history.", "method": "GET", "path": "/api/deals/{id}/history", "permission": "deals:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get deal history.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/deals/00000000-0000-4000-8000-000000000000/history", "body": null }, "effects": "Reads state through GET /api/deals/{id}/history without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/deals/*/history", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "deals.pipeline_board.get", "title": "Get deal pipeline board", "description": "Get CRM deal pipeline board.", "method": "GET", "path": "/api/deals/pipeline/{pipelineId}/board", "permission": "deals:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pipelineId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "pipelineId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get deal pipeline board.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "pipelineId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/deals/pipeline/example/board", "body": null }, "effects": "Reads state through GET /api/deals/pipeline/{pipelineId}/board without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/deals/pipeline/*/board", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pipeline.list", "title": "List pipelines", "description": "List CRM pipelines.", "method": "GET", "path": "/api/pipeline", "permission": "pipeline:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List pipelines.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/pipeline", "body": null }, "effects": "Reads state through GET /api/pipeline without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/pipeline", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pipeline.get", "title": "Get pipeline", "description": "Get a CRM pipeline.", "method": "GET", "path": "/api/pipeline/{pipelineId}", "permission": "pipeline:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pipelineId": { "type": "string", "minLength": 1 } }, "required": [ "pipelineId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get pipeline.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "pipelineId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/pipeline/example", "body": null }, "effects": "Reads state through GET /api/pipeline/{pipelineId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/pipeline/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pipeline.board.get", "title": "Get pipeline board", "description": "Get a CRM pipeline board.", "method": "GET", "path": "/api/pipeline/{pipelineId}/board", "permission": "pipeline:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pipelineId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "pipelineId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get pipeline board.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "pipelineId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/pipeline/example/board", "body": null }, "effects": "Reads state through GET /api/pipeline/{pipelineId}/board without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/pipeline/*/board", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pipeline.stages.list", "title": "List pipeline stages", "description": "List CRM pipeline stages.", "method": "GET", "path": "/api/pipeline/{pipelineId}/stages", "permission": "pipeline:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pipelineId": { "type": "string", "minLength": 1 } }, "required": [ "pipelineId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List pipeline stages.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "pipelineId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/pipeline/example/stages", "body": null }, "effects": "Reads state through GET /api/pipeline/{pipelineId}/stages without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/pipeline/*/stages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pipeline.structure.get", "title": "Get pipeline structure", "description": "Get CRM pipeline structure.", "method": "GET", "path": "/api/pipeline/{pipelineId}/structure", "permission": "pipeline:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pipelineId": { "type": "string", "minLength": 1 } }, "required": [ "pipelineId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get pipeline structure.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "pipelineId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/pipeline/example/structure", "body": null }, "effects": "Reads state through GET /api/pipeline/{pipelineId}/structure without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/pipeline/*/structure", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pipeline.contact.status.get", "title": "Get contact pipeline status", "description": "Get CRM contact pipeline status.", "method": "GET", "path": "/api/pipeline/{contactId}/status", "permission": "pipeline:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 } }, "required": [ "contactId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get contact pipeline status.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "contactId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/pipeline/example/status", "body": null }, "effects": "Reads state through GET /api/pipeline/{contactId}/status without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/pipeline/*/status", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pipeline.contact.history.get", "title": "Get contact pipeline history", "description": "Get CRM contact pipeline history.", "method": "GET", "path": "/api/pipeline/{contactId}/history", "permission": "pipeline:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 } }, "required": [ "contactId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get contact pipeline history.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "contactId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/pipeline/example/history", "body": null }, "effects": "Reads state through GET /api/pipeline/{contactId}/history without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/pipeline/*/history", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pipeline.contact.add", "title": "Add contact to pipeline", "description": "Add a CRM contact to a pipeline.", "method": "POST", "path": "/api/pipeline/{contactId}/add", "permission": "pipeline:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 }, "stageId": { "type": "string", "minLength": 1 } }, "required": [ "contactId", "stageId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Add contact to pipeline.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "contactId": "example", "stageId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/pipeline/example/add", "body": { "contactId": "example", "stageId": "example" } }, "effects": "May change state through POST /api/pipeline/{contactId}/add. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/pipeline/*/add", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pipeline.contact.move", "title": "Move contact in pipeline", "description": "Move a CRM contact in a pipeline.", "method": "PUT", "path": "/api/pipeline/{contactId}/move", "permission": "pipeline:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 }, "stageId": { "type": "string", "minLength": 1 } }, "required": [ "contactId", "stageId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Move contact in pipeline.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "contactId": "example", "stageId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/pipeline/example/move", "body": { "contactId": "example", "stageId": "example" } }, "effects": "May change state through PUT /api/pipeline/{contactId}/move. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/pipeline/*/move", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pipeline.contact.remove", "title": "Remove contact from pipeline", "description": "Remove a CRM contact from a pipeline.", "method": "DELETE", "path": "/api/pipeline/{contactId}/remove", "permission": "pipeline:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 } }, "required": [ "contactId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Remove contact from pipeline.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "contactId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/pipeline/example/remove", "body": null }, "effects": "May change state through DELETE /api/pipeline/{contactId}/remove. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/pipeline/*/remove", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pipeline.stages.update", "title": "Update pipeline stage", "description": "Update a CRM pipeline stage.", "method": "PUT", "path": "/api/pipeline/stages/{stageId}", "permission": "pipeline:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "stageId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "color": { "type": "string" }, "position": { "type": "number" } }, "required": [ "stageId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update pipeline stage.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "stageId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/pipeline/stages/example", "body": { "stageId": "example" } }, "effects": "May change state through PUT /api/pipeline/stages/{stageId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/pipeline/stages/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "properties.list", "title": "List properties", "description": "List properties.", "method": "GET", "path": "/api/properties", "permission": "properties:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "status": { "type": "string" }, "property_type": { "type": "string" }, "assigned_agent_id": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "beds_min": { "type": "number" }, "beds_max": { "type": "number" }, "baths_min": { "type": "number" }, "baths_max": { "type": "number" }, "sqft_min": { "type": "number" }, "sqft_max": { "type": "number" }, "created_after": { "type": "string" }, "updated_after": { "type": "string" }, "sort_by": { "type": "string" }, "sort_order": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List properties.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "search": "example", "status": "example", "property_type": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/properties", "body": null }, "effects": "Reads state through GET /api/properties without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/properties", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "properties.create", "title": "Create properties", "description": "Create properties.", "method": "POST", "path": "/api/properties", "permission": "properties:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "property_type": { "type": "string" }, "status": { "type": "string" }, "address_line1": { "type": "string" }, "address_line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "furnishing_status": { "type": "string" }, "owner_contact_id": { "type": "string" }, "owner_company_id": { "type": "string" }, "assigned_agent_id": { "type": "string" }, "primary_photo_bytes_asset_id": { "type": "string" }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "beds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "baths": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sqft": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lot_size": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "year_built": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "parking_spaces": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create properties.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "property_type": "example", "status": "example", "address_line1": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/properties", "body": { "property_type": "example", "status": "example", "address_line1": "example" } }, "effects": "May change state through POST /api/properties. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/properties", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "properties.get", "title": "Get properties", "description": "Get one properties record.", "method": "GET", "path": "/api/properties/{id}", "permission": "properties:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get properties.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/properties/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/properties/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/properties/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "properties.update", "title": "Update properties", "description": "Update one properties record.", "method": "PUT", "path": "/api/properties/{id}", "permission": "properties:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "property_type": { "type": "string" }, "status": { "type": "string" }, "address_line1": { "type": "string" }, "address_line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "furnishing_status": { "type": "string" }, "owner_contact_id": { "type": "string" }, "owner_company_id": { "type": "string" }, "assigned_agent_id": { "type": "string" }, "primary_photo_bytes_asset_id": { "type": "string" }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "beds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "baths": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sqft": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lot_size": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "year_built": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "parking_spaces": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update properties.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/properties/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/properties/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/properties/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "properties.delete", "title": "Delete properties", "description": "Delete one properties record.", "method": "DELETE", "path": "/api/properties/{id}", "permission": "properties:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete properties.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/properties/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/properties/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/properties/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "listings.list", "title": "List listings", "description": "List listings.", "method": "GET", "path": "/api/listings", "permission": "listings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "property_id": { "type": "string" }, "listing_type": { "type": "string" }, "internal_status": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "price_min": { "type": "number" }, "price_max": { "type": "number" }, "canonical_completeness_min": { "type": "number" }, "canonical_completeness_max": { "type": "number" }, "created_after": { "type": "string" }, "updated_after": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List listings.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "search": "example", "property_id": "00000000-0000-4000-8000-000000000000", "listing_type": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/listings", "body": null }, "effects": "Reads state through GET /api/listings without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/listings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "listings.create", "title": "Create listings", "description": "Create listings.", "method": "POST", "path": "/api/listings", "permission": "listings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "property_id": { "type": "string" }, "listing_type": { "type": "string" }, "internal_status": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" }, "permit_number": { "type": "string" }, "reference_code": { "type": "string" }, "description_short": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description_long": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price_amount": { "type": "number" }, "availability_date": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create listings.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "property_id": "00000000-0000-4000-8000-000000000000", "listing_type": "example", "internal_status": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/listings", "body": { "property_id": "00000000-0000-4000-8000-000000000000", "listing_type": "example", "internal_status": "example" } }, "effects": "May change state through POST /api/listings. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/listings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "listings.get", "title": "Get listings", "description": "Get one listings record.", "method": "GET", "path": "/api/listings/{id}", "permission": "listings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get listings.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/listings/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/listings/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/listings/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "listings.update", "title": "Update listings", "description": "Update one listings record.", "method": "PUT", "path": "/api/listings/{id}", "permission": "listings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "property_id": { "type": "string" }, "listing_type": { "type": "string" }, "internal_status": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" }, "permit_number": { "type": "string" }, "reference_code": { "type": "string" }, "description_short": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description_long": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price_amount": { "type": "number" }, "availability_date": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update listings.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/listings/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/listings/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/listings/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "listings.delete", "title": "Delete listings", "description": "Delete one listings record.", "method": "DELETE", "path": "/api/listings/{id}", "permission": "listings:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete listings.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/listings/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/listings/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/listings/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "listings.validate", "title": "Validate listing", "description": "Validate a CRM listing.", "method": "POST", "path": "/api/listings/{id}/validate", "permission": "listings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "property_id": { "type": "string" }, "listing_type": { "type": "string" }, "internal_status": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" }, "permit_number": { "type": "string" }, "reference_code": { "type": "string" }, "description_short": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description_long": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price_amount": { "type": "number" }, "availability_date": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Validate listing.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/listings/00000000-0000-4000-8000-000000000000/validate", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/listings/{id}/validate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/listings/*/validate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "listings.publications.list", "title": "List listing publications", "description": "List CRM listing publications.", "method": "GET", "path": "/api/listings/{id}/publications", "permission": "listings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List listing publications.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/listings/00000000-0000-4000-8000-000000000000/publications", "body": null }, "effects": "Reads state through GET /api/listings/{id}/publications without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/listings/*/publications", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_connections.list", "title": "List portal connections", "description": "List portal connections.", "method": "GET", "path": "/api/portal-connections", "permission": "portal_connections:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "status": { "type": "string" }, "portal_key": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List portal connections.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "search": "example", "status": "example", "portal_key": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/portal-connections", "body": null }, "effects": "Reads state through GET /api/portal-connections without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/portal-connections", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_connections.create", "title": "Create portal connections", "description": "Create portal connections.", "method": "POST", "path": "/api/portal-connections", "permission": "portal_connections:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "portal_key": { "type": "string" }, "account_name": { "type": "string" }, "connector_type": { "type": "string" }, "auth_type": { "type": "string" }, "credentials_ref": { "type": "string" }, "market_region": { "type": "string" }, "status": { "type": "string" }, "connector_config": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create portal connections.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "portal_key": "example", "account_name": "example", "connector_type": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/portal-connections", "body": { "portal_key": "example", "account_name": "example", "connector_type": "example" } }, "effects": "May change state through POST /api/portal-connections. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/portal-connections", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_connections.get", "title": "Get portal connections", "description": "Get one portal connections record.", "method": "GET", "path": "/api/portal-connections/{id}", "permission": "portal_connections:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get portal connections.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/portal-connections/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/portal-connections/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/portal-connections/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_connections.update", "title": "Update portal connections", "description": "Update one portal connections record.", "method": "PUT", "path": "/api/portal-connections/{id}", "permission": "portal_connections:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "portal_key": { "type": "string" }, "account_name": { "type": "string" }, "connector_type": { "type": "string" }, "auth_type": { "type": "string" }, "credentials_ref": { "type": "string" }, "market_region": { "type": "string" }, "status": { "type": "string" }, "connector_config": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update portal connections.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/portal-connections/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/portal-connections/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/portal-connections/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_connections.delete", "title": "Delete portal connections", "description": "Delete one portal connections record.", "method": "DELETE", "path": "/api/portal-connections/{id}", "permission": "portal_connections:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete portal connections.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/portal-connections/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/portal-connections/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/portal-connections/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_connections.health_check", "title": "Run portal connection health check", "description": "Run a CRM portal connection health check.", "method": "POST", "path": "/api/portal-connections/{id}/health-check", "permission": "portal_connections:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "portal_key": { "type": "string" }, "account_name": { "type": "string" }, "connector_type": { "type": "string" }, "auth_type": { "type": "string" }, "credentials_ref": { "type": "string" }, "market_region": { "type": "string" }, "status": { "type": "string" }, "connector_config": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Run portal connection health check.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/portal-connections/00000000-0000-4000-8000-000000000000/health-check", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/portal-connections/{id}/health-check. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/portal-connections/*/health-check", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_connections.disable", "title": "Disable portal connection", "description": "Disable a CRM portal connection.", "method": "POST", "path": "/api/portal-connections/{id}/disable", "permission": "portal_connections:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "portal_key": { "type": "string" }, "account_name": { "type": "string" }, "connector_type": { "type": "string" }, "auth_type": { "type": "string" }, "credentials_ref": { "type": "string" }, "market_region": { "type": "string" }, "status": { "type": "string" }, "connector_config": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Disable portal connection.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/portal-connections/00000000-0000-4000-8000-000000000000/disable", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/portal-connections/{id}/disable. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/portal-connections/*/disable", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_leads.list", "title": "List portal leads", "description": "List CRM portal leads.", "method": "GET", "path": "/api/portal-leads", "permission": "portal_leads:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "portal_key": { "type": "string" }, "ingestion_status": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List portal leads.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "search": "example", "portal_key": "example", "ingestion_status": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/portal-leads", "body": null }, "effects": "Reads state through GET /api/portal-leads without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/portal-leads", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_leads.get", "title": "Get portal lead", "description": "Get a CRM portal lead.", "method": "GET", "path": "/api/portal-leads/{id}", "permission": "portal_leads:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get portal lead.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/portal-leads/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/portal-leads/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/portal-leads/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_leads.match", "title": "Match portal lead", "description": "Match a CRM portal lead.", "method": "POST", "path": "/api/portal-leads/{id}/match", "permission": "portal_leads:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "contact_id": { "type": "string" }, "create_if_missing": { "type": "boolean" }, "create_deal": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Match portal lead.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/portal-leads/00000000-0000-4000-8000-000000000000/match", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/portal-leads/{id}/match. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/portal-leads/*/match", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_leads.create_contact", "title": "Create contact from portal lead", "description": "Create a CRM contact from a portal lead.", "method": "POST", "path": "/api/portal-leads/{id}/create-contact", "permission": "portal_leads:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "first": { "type": "string" }, "last": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create contact from portal lead.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/portal-leads/00000000-0000-4000-8000-000000000000/create-contact", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/portal-leads/{id}/create-contact. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/portal-leads/*/create-contact", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_leads.create_deal", "title": "Create deal from portal lead", "description": "Create a CRM deal from a portal lead.", "method": "POST", "path": "/api/portal-leads/{id}/create-deal", "permission": "portal_leads:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "amount_cents": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create deal from portal lead.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/portal-leads/00000000-0000-4000-8000-000000000000/create-deal", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/portal-leads/{id}/create-deal. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/portal-leads/*/create-deal", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "lead_routing.rules.list", "title": "List lead routing rules", "description": "List CRM lead routing rules.", "method": "GET", "path": "/api/lead-routing/rules", "permission": "portal_leads:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List lead routing rules.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/lead-routing/rules", "body": null }, "effects": "Reads state through GET /api/lead-routing/rules without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/lead-routing/rules", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "lead_routing.rules.create", "title": "Create lead routing rule", "description": "Create a CRM lead routing rule.", "method": "POST", "path": "/api/lead-routing/rules", "permission": "portal_leads:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "portal_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assigned_agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fallback_owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "auto_create_task": { "type": "boolean" }, "task_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create lead routing rule.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "name": "example", "portal_key": "example", "assigned_agent_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/lead-routing/rules", "body": { "name": "example", "portal_key": "example", "assigned_agent_id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/lead-routing/rules. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/lead-routing/rules", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "lead_routing.rules.update", "title": "Update lead routing rule", "description": "Update a CRM lead routing rule.", "method": "PUT", "path": "/api/lead-routing/rules/{id}", "permission": "portal_leads:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "portal_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assigned_agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fallback_owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "auto_create_task": { "type": "boolean" }, "task_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update lead routing rule.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/lead-routing/rules/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/lead-routing/rules/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/lead-routing/rules/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "tasks.list", "title": "List tasks", "description": "List tasks.", "method": "GET", "path": "/api/tasks", "permission": "tasks:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "owner_id": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List tasks.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "search": "example", "status": "example", "priority": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/tasks", "body": null }, "effects": "Reads state through GET /api/tasks without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/tasks", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "tasks.create", "title": "Create tasks", "description": "Create tasks.", "method": "POST", "path": "/api/tasks", "permission": "tasks:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "owner_id": { "type": "string" }, "due_at": { "type": "string" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create tasks.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "title": "example", "description": "example", "status": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/tasks", "body": { "title": "example", "description": "example", "status": "example" } }, "effects": "May change state through POST /api/tasks. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/tasks", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "tasks.update", "title": "Update tasks", "description": "Update one tasks record.", "method": "PUT", "path": "/api/tasks/{id}", "permission": "tasks:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "owner_id": { "type": "string" }, "due_at": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update tasks.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/tasks/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/tasks/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/tasks/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "tasks.delete", "title": "Delete tasks", "description": "Delete one tasks record.", "method": "DELETE", "path": "/api/tasks/{id}", "permission": "tasks:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete tasks.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/tasks/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/tasks/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/tasks/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "showings.list", "title": "List showings", "description": "List showings.", "method": "GET", "path": "/api/showings", "permission": "showings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "property_id": { "type": "string" }, "listing_id": { "type": "string" }, "status": { "type": "string" }, "assigned_agent_id": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List showings.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "search": "example", "property_id": "00000000-0000-4000-8000-000000000000", "listing_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/showings", "body": null }, "effects": "Reads state through GET /api/showings without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/showings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "showings.create", "title": "Create showings", "description": "Create showings.", "method": "POST", "path": "/api/showings", "permission": "showings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "property_id": { "type": "string" }, "listing_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "portal_lead_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "attendee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attendee_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attendee_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduled_at": { "type": "number" }, "duration_minutes": { "type": "number" }, "status": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assigned_agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create showings.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "property_id": "00000000-0000-4000-8000-000000000000", "listing_id": "00000000-0000-4000-8000-000000000000", "portal_lead_event_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/showings", "body": { "property_id": "00000000-0000-4000-8000-000000000000", "listing_id": "00000000-0000-4000-8000-000000000000", "portal_lead_event_id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/showings. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/showings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "showings.get", "title": "Get showings", "description": "Get one showings record.", "method": "GET", "path": "/api/showings/{id}", "permission": "showings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get showings.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/showings/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/showings/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/showings/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "showings.update", "title": "Update showings", "description": "Update one showings record.", "method": "PUT", "path": "/api/showings/{id}", "permission": "showings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "property_id": { "type": "string" }, "listing_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "portal_lead_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "attendee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attendee_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attendee_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduled_at": { "type": "number" }, "duration_minutes": { "type": "number" }, "status": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assigned_agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update showings.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/showings/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/showings/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/showings/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "showings.delete", "title": "Delete showings", "description": "Delete one showings record.", "method": "DELETE", "path": "/api/showings/{id}", "permission": "showings:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete showings.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/showings/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/showings/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/showings/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "offers.list", "title": "List offers", "description": "List offers.", "method": "GET", "path": "/api/offers", "permission": "offers:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "property_id": { "type": "string" }, "listing_id": { "type": "string" }, "status": { "type": "string" }, "contact_id": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List offers.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "search": "example", "property_id": "00000000-0000-4000-8000-000000000000", "listing_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/offers", "body": null }, "effects": "Reads state through GET /api/offers without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/offers", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "offers.create", "title": "Create offers", "description": "Create offers.", "method": "POST", "path": "/api/offers", "permission": "offers:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "property_id": { "type": "string" }, "listing_id": { "type": "string" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "amount_cents": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "expiry_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "contingencies": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create offers.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "property_id": "00000000-0000-4000-8000-000000000000", "listing_id": "00000000-0000-4000-8000-000000000000", "contact_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/offers", "body": { "property_id": "00000000-0000-4000-8000-000000000000", "listing_id": "00000000-0000-4000-8000-000000000000", "contact_id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/offers. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/offers", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "offers.get", "title": "Get offers", "description": "Get one offers record.", "method": "GET", "path": "/api/offers/{id}", "permission": "offers:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get offers.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/offers/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/offers/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/offers/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "offers.update", "title": "Update offers", "description": "Update one offers record.", "method": "PUT", "path": "/api/offers/{id}", "permission": "offers:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "property_id": { "type": "string" }, "listing_id": { "type": "string" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "amount_cents": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "expiry_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "contingencies": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update offers.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/offers/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/offers/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/offers/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "offers.delete", "title": "Delete offers", "description": "Delete one offers record.", "method": "DELETE", "path": "/api/offers/{id}", "permission": "offers:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete offers.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/offers/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/offers/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/offers/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "transactions.list", "title": "List transactions", "description": "List transactions.", "method": "GET", "path": "/api/transactions", "permission": "transactions:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "status": { "type": "string" }, "property_id": { "type": "string" }, "listing_id": { "type": "string" }, "offer_id": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List transactions.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "search": "example", "status": "example", "property_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/transactions", "body": null }, "effects": "Reads state through GET /api/transactions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/transactions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "transactions.create", "title": "Create transactions", "description": "Create transactions.", "method": "POST", "path": "/api/transactions", "permission": "transactions:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "property_id": { "type": "string" }, "listing_id": { "type": "string" }, "offer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "status": { "type": "string" }, "escrow_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "closing_date": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "assigned_coordinator_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create transactions.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "property_id": "00000000-0000-4000-8000-000000000000", "listing_id": "00000000-0000-4000-8000-000000000000", "offer_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/transactions", "body": { "property_id": "00000000-0000-4000-8000-000000000000", "listing_id": "00000000-0000-4000-8000-000000000000", "offer_id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/transactions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/transactions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "transactions.get", "title": "Get transactions", "description": "Get one transactions record.", "method": "GET", "path": "/api/transactions/{id}", "permission": "transactions:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get transactions.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/transactions/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/transactions/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/transactions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "transactions.update", "title": "Update transactions", "description": "Update one transactions record.", "method": "PUT", "path": "/api/transactions/{id}", "permission": "transactions:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "property_id": { "type": "string" }, "listing_id": { "type": "string" }, "offer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "status": { "type": "string" }, "escrow_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "closing_date": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "assigned_coordinator_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update transactions.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/transactions/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/transactions/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/transactions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "transactions.delete", "title": "Delete transactions", "description": "Delete one transactions record.", "method": "DELETE", "path": "/api/transactions/{id}", "permission": "transactions:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete transactions.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/transactions/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/transactions/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/transactions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "transactions.milestones.create", "title": "Create transaction milestone", "description": "Create a CRM transaction milestone.", "method": "POST", "path": "/api/transactions/{id}/milestones", "permission": "transactions:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "status": { "type": "string" }, "due_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sort_order": { "type": "number" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create transaction milestone.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/transactions/00000000-0000-4000-8000-000000000000/milestones", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/transactions/{id}/milestones. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/transactions/*/milestones", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "transactions.milestones.update", "title": "Update transaction milestone", "description": "Update a CRM transaction milestone.", "method": "PUT", "path": "/api/transactions/{transactionId}/milestones/{milestoneId}", "permission": "transactions:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transactionId": { "type": "string", "minLength": 1 }, "milestoneId": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "status": { "type": "string" }, "due_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sort_order": { "type": "number" } }, "required": [ "transactionId", "milestoneId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update transaction milestone.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "transactionId": "example", "milestoneId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/transactions/example/milestones/example", "body": { "transactionId": "example", "milestoneId": "example" } }, "effects": "May change state through PUT /api/transactions/{transactionId}/milestones/{milestoneId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/transactions/*/milestones/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "transactions.checklist.create", "title": "Create transaction checklist item", "description": "Create a CRM transaction checklist item.", "method": "POST", "path": "/api/transactions/{id}/checklist", "permission": "transactions:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "required": { "type": "boolean" }, "status": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "due_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create transaction checklist item.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/transactions/00000000-0000-4000-8000-000000000000/checklist", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/transactions/{id}/checklist. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/transactions/*/checklist", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "transactions.checklist.update", "title": "Update transaction checklist item", "description": "Update a CRM transaction checklist item.", "method": "PUT", "path": "/api/transactions/{transactionId}/checklist/{itemId}", "permission": "transactions:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transactionId": { "type": "string", "minLength": 1 }, "itemId": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "required": { "type": "boolean" }, "status": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "due_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "transactionId", "itemId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update transaction checklist item.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "transactionId": "example", "itemId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/transactions/example/checklist/example", "body": { "transactionId": "example", "itemId": "example" } }, "effects": "May change state through PUT /api/transactions/{transactionId}/checklist/{itemId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/transactions/*/checklist/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "transactions.documents.create", "title": "Create transaction document", "description": "Create a CRM transaction document.", "method": "POST", "path": "/api/transactions/{id}/documents", "permission": "documents:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "url": { "type": "string" }, "document_type": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create transaction document.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/transactions/00000000-0000-4000-8000-000000000000/documents", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/transactions/{id}/documents. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/transactions/*/documents", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "transactions.documents.get", "title": "Get transaction document", "description": "Get a CRM transaction document.", "method": "GET", "path": "/api/transactions/{transactionId}/documents/{documentId}", "permission": "documents:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transactionId": { "type": "string", "minLength": 1 }, "documentId": { "type": "string", "minLength": 1 } }, "required": [ "transactionId", "documentId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get transaction document.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "transactionId": "example", "documentId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/transactions/example/documents/example", "body": null }, "effects": "Reads state through GET /api/transactions/{transactionId}/documents/{documentId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/transactions/*/documents/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "transactions.documents.delete", "title": "Delete transaction document", "description": "Delete a CRM transaction document.", "method": "DELETE", "path": "/api/transactions/{transactionId}/documents/{documentId}", "permission": "documents:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transactionId": { "type": "string", "minLength": 1 }, "documentId": { "type": "string", "minLength": 1 } }, "required": [ "transactionId", "documentId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete transaction document.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "transactionId": "example", "documentId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/transactions/example/documents/example", "body": null }, "effects": "May change state through DELETE /api/transactions/{transactionId}/documents/{documentId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/transactions/*/documents/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "commissions.list", "title": "List commissions", "description": "List commissions.", "method": "GET", "path": "/api/commissions", "permission": "commissions:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transaction_id": { "type": "string" }, "status": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List commissions.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "transaction_id": "00000000-0000-4000-8000-000000000000", "status": "example", "page": 1 }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/commissions", "body": null }, "effects": "Reads state through GET /api/commissions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/commissions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "commissions.create", "title": "Create commissions", "description": "Create commissions.", "method": "POST", "path": "/api/commissions", "permission": "commissions:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transaction_id": { "type": "string" }, "recipient_type": { "type": "string" }, "recipient_id": { "type": "string" }, "recipient_name": { "type": "string" }, "status": { "type": "string" }, "split_bps": { "type": "number" }, "amount_cents": { "type": "number" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create commissions.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "transaction_id": "00000000-0000-4000-8000-000000000000", "recipient_type": "example", "recipient_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/commissions", "body": { "transaction_id": "00000000-0000-4000-8000-000000000000", "recipient_type": "example", "recipient_id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/commissions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/commissions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "commissions.update", "title": "Update commissions", "description": "Update one commissions record.", "method": "PUT", "path": "/api/commissions/{id}", "permission": "commissions:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "transaction_id": { "type": "string" }, "recipient_type": { "type": "string" }, "recipient_id": { "type": "string" }, "recipient_name": { "type": "string" }, "status": { "type": "string" }, "split_bps": { "type": "number" }, "amount_cents": { "type": "number" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update commissions.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/commissions/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/commissions/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/commissions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "commissions.delete", "title": "Delete commissions", "description": "Delete one commissions record.", "method": "DELETE", "path": "/api/commissions/{id}", "permission": "commissions:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete commissions.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/commissions/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/commissions/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/commissions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "notes.list", "title": "List contact notes", "description": "List CRM contact notes.", "method": "GET", "path": "/api/contacts/{id}/notes", "permission": "notes:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List contact notes.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/contacts/00000000-0000-4000-8000-000000000000/notes", "body": null }, "effects": "Reads state through GET /api/contacts/{id}/notes without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/contacts/*/notes", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "notes.create", "title": "Create contact note", "description": "Create a CRM contact note.", "method": "POST", "path": "/api/contacts/{id}/notes", "permission": "notes:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "body": { "type": "string" }, "text": { "type": "string" }, "category": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create contact note.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/contacts/00000000-0000-4000-8000-000000000000/notes", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/contacts/{id}/notes. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/contacts/*/notes", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "notes.get", "title": "Get contact note", "description": "Get a CRM contact note.", "method": "GET", "path": "/api/contacts/{contactId}/notes/{noteId}", "permission": "notes:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 }, "noteId": { "type": "string", "minLength": 1 } }, "required": [ "contactId", "noteId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get contact note.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "contactId": "example", "noteId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/contacts/example/notes/example", "body": null }, "effects": "Reads state through GET /api/contacts/{contactId}/notes/{noteId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/contacts/*/notes/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "notes.update", "title": "Update contact note", "description": "Update a CRM contact note.", "method": "PUT", "path": "/api/contacts/{contactId}/notes/{noteId}", "permission": "notes:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 }, "noteId": { "type": "string", "minLength": 1 }, "body": { "type": "string" }, "text": { "type": "string" }, "category": { "type": "string" } }, "required": [ "contactId", "noteId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update contact note.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "contactId": "example", "noteId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/contacts/example/notes/example", "body": { "contactId": "example", "noteId": "example" } }, "effects": "May change state through PUT /api/contacts/{contactId}/notes/{noteId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/contacts/*/notes/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "notes.delete", "title": "Delete contact note", "description": "Delete a CRM contact note.", "method": "DELETE", "path": "/api/contacts/{contactId}/notes/{noteId}", "permission": "notes:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 }, "noteId": { "type": "string", "minLength": 1 } }, "required": [ "contactId", "noteId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete contact note.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "contactId": "example", "noteId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/contacts/example/notes/example", "body": null }, "effects": "May change state through DELETE /api/contacts/{contactId}/notes/{noteId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/contacts/*/notes/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "attachments.create", "title": "Create contact attachment", "description": "Create a CRM contact attachment.", "method": "POST", "path": "/api/contacts/{id}/attachments", "permission": "attachments:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string" }, "contentType": { "type": "string" }, "fileName": { "type": "string" }, "media_role": { "type": "string" }, "set_primary": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ] } }, "required": [ "id", "contentBase64", "contentType", "fileName" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create contact attachment.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "upload": { "profile": "inline-base64", "contentField": "contentBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 10485760, "acceptedContentTypes": [ "*/*" ] } }, "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "contentBase64": "example", "contentType": "example", "fileName": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/contacts/00000000-0000-4000-8000-000000000000/attachments", "body": { "id": "00000000-0000-4000-8000-000000000000", "contentBase64": "example", "contentType": "example", "fileName": "example" } }, "effects": "May change state through POST /api/contacts/{id}/attachments. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/contacts/*/attachments", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "attachments.list", "title": "List contact attachments", "description": "List CRM contact attachments.", "method": "GET", "path": "/api/contacts/{id}/attachments", "permission": "attachments:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List contact attachments.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/contacts/00000000-0000-4000-8000-000000000000/attachments", "body": null }, "effects": "Reads state through GET /api/contacts/{id}/attachments without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/contacts/*/attachments", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "attachments.get", "title": "Get attachment", "description": "Get a CRM attachment.", "method": "GET", "path": "/api/attachments/{id}", "permission": "attachments:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get attachment.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/attachments/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/attachments/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/attachments/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "attachments.delete", "title": "Delete attachment", "description": "Delete a CRM attachment.", "method": "DELETE", "path": "/api/attachments/{id}", "permission": "attachments:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete attachment.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/attachments/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/attachments/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/attachments/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "dashboard.real_estate.get", "title": "Get real estate dashboard", "description": "Get CRM real estate dashboard.", "method": "GET", "path": "/api/dashboard/real-estate", "permission": "reports:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string" }, "window_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get real estate dashboard.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "scope": "example", "window_days": 1 }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/dashboard/real-estate", "body": null }, "effects": "Reads state through GET /api/dashboard/real-estate without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/dashboard/real-estate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "dashboard.core.get", "title": "Get core dashboard", "description": "Get CRM core dashboard.", "method": "GET", "path": "/api/dashboard/core", "permission": "reports:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get core dashboard.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/dashboard/core", "body": null }, "effects": "Reads state through GET /api/dashboard/core without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/dashboard/core", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "saved_views.list", "title": "List saved views", "description": "List saved views.", "method": "GET", "path": "/api/saved-views", "permission": "settings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "module_key": { "type": "string" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List saved views.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "module_key": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/saved-views", "body": null }, "effects": "Reads state through GET /api/saved-views without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/saved-views", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "saved_views.create", "title": "Create saved views", "description": "Create saved views.", "method": "POST", "path": "/api/saved-views", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "module_key": { "type": "string" }, "required": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create saved views.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "name": "example", "module_key": "example", "required": true }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/saved-views", "body": { "name": "example", "module_key": "example", "required": true } }, "effects": "May change state through POST /api/saved-views. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/saved-views", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "saved_views.update", "title": "Update saved views", "description": "Update one saved views record.", "method": "PUT", "path": "/api/saved-views/{id}", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "module_key": { "type": "string" }, "required": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update saved views.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/saved-views/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/saved-views/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/saved-views/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "saved_views.delete", "title": "Delete saved views", "description": "Delete one saved views record.", "method": "DELETE", "path": "/api/saved-views/{id}", "permission": "settings:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete saved views.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/saved-views/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/saved-views/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/saved-views/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "settings.org.get", "title": "Get organization settings", "description": "Get CRM organization settings.", "method": "GET", "path": "/api/settings/org", "permission": "settings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get organization settings.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/settings/org", "body": null }, "effects": "Reads state through GET /api/settings/org without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/settings/org", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "settings.org.update", "title": "Update organization settings", "description": "Update CRM organization settings.", "method": "PUT", "path": "/api/settings/org", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "module_settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "role_defaults": { "type": "array", "items": { "type": "object", "properties": { "role_key": { "type": "string" }, "landing_path": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update organization settings.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "module_settings": {}, "role_defaults": [ { "role_key": "example", "landing_path": "example" } ] }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/settings/org", "body": { "module_settings": {}, "role_defaults": [ { "role_key": "example", "landing_path": "example" } ] } }, "effects": "May change state through PUT /api/settings/org. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/settings/org", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "search.run", "title": "Search CRM", "description": "Run CRM search.", "method": "GET", "path": "/api/search", "permission": "search:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Search CRM.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "q": "example", "limit": 1 }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/search", "body": null }, "effects": "Reads state through GET /api/search without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/search", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "import_export.preview", "title": "Preview import", "description": "Preview a CRM import.", "method": "POST", "path": "/api/import-export/preview", "permission": "contacts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "csvData": { "type": "string" }, "delimiter": { "type": "string" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Preview import.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "csvData": "example", "delimiter": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/import-export/preview", "body": { "csvData": "example", "delimiter": "example" } }, "effects": "May change state through POST /api/import-export/preview. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/import-export/preview", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "import_export.execute", "title": "Execute import", "description": "Execute a CRM import.", "method": "POST", "path": "/api/import-export/execute", "permission": "contacts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "csvData": { "type": "string" }, "columnMapping": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "delimiter": { "type": "string" }, "createCompanies": { "type": "boolean" }, "fileName": { "type": "string" }, "storeSourceRows": { "type": "boolean" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Execute import.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "csvData": "example", "columnMapping": {}, "delimiter": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/import-export/execute", "body": { "csvData": "example", "columnMapping": {}, "delimiter": "example" } }, "effects": "May change state through POST /api/import-export/execute. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/import-export/execute", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "import_export.template.get", "title": "Get import template", "description": "Get a CRM import template.", "method": "GET", "path": "/api/import-export/template", "permission": "contacts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "module_key": { "type": "string" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get import template.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "module_key": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/import-export/template", "body": null }, "effects": "Reads state through GET /api/import-export/template without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/import-export/template", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "import_export.bulk", "title": "Run bulk import", "description": "Run a CRM bulk import.", "method": "POST", "path": "/api/import-export/bulk", "permission": "contacts:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "companies": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "notes": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Run bulk import.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "contacts": [ {} ], "companies": [ {} ], "notes": [ {} ] }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/import-export/bulk", "body": { "contacts": [ {} ], "companies": [ {} ], "notes": [ {} ] } }, "effects": "May change state through POST /api/import-export/bulk. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/import-export/bulk", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "import_export.export", "title": "Export CRM data", "description": "Export CRM data.", "method": "GET", "path": "/api/import-export/export", "permission": "contacts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "includeDeleted": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Export CRM data.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "includeDeleted": true, "limit": 1 }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/import-export/export", "body": null }, "effects": "Reads state through GET /api/import-export/export without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/import-export/export", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_sync.listing.publish", "title": "Publish listing", "description": "Publish a CRM listing.", "method": "POST", "path": "/api/listings/{id}/publish", "permission": "portal_sync:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "portal_connection_ids": { "type": "array", "items": { "type": "string" } }, "force_refresh": { "type": "boolean" }, "dry_run": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Publish listing.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/listings/00000000-0000-4000-8000-000000000000/publish", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/listings/{id}/publish. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/listings/*/publish", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_sync.listing.unpublish", "title": "Unpublish listing", "description": "Unpublish a CRM listing.", "method": "POST", "path": "/api/listings/{id}/unpublish", "permission": "portal_sync:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "portal_connection_ids": { "type": "array", "items": { "type": "string" } }, "force_refresh": { "type": "boolean" }, "dry_run": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Unpublish listing.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/listings/00000000-0000-4000-8000-000000000000/unpublish", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/listings/{id}/unpublish. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/listings/*/unpublish", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_sync.listing.refresh", "title": "Refresh listing sync", "description": "Refresh CRM listing sync.", "method": "POST", "path": "/api/listings/{id}/refresh", "permission": "portal_sync:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "portal_connection_ids": { "type": "array", "items": { "type": "string" } }, "force_refresh": { "type": "boolean" }, "dry_run": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Refresh listing sync.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/listings/00000000-0000-4000-8000-000000000000/refresh", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/listings/{id}/refresh. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/listings/*/refresh", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_sync.listing.retry", "title": "Retry listing sync", "description": "Retry CRM listing sync.", "method": "POST", "path": "/api/listings/{id}/retry-sync", "permission": "portal_sync:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "portal_connection_ids": { "type": "array", "items": { "type": "string" } }, "force_refresh": { "type": "boolean" }, "dry_run": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Retry listing sync.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/listings/00000000-0000-4000-8000-000000000000/retry-sync", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/listings/{id}/retry-sync. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/listings/*/retry-sync", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_sync.jobs.list", "title": "List listing sync jobs", "description": "List CRM listing sync jobs.", "method": "GET", "path": "/api/listings/{id}/sync-jobs", "permission": "portal_sync:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List listing sync jobs.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/listings/00000000-0000-4000-8000-000000000000/sync-jobs", "body": null }, "effects": "Reads state through GET /api/listings/{id}/sync-jobs without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/listings/*/sync-jobs", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_sync.publications.get", "title": "Get portal publication", "description": "Get a CRM portal publication.", "method": "GET", "path": "/api/publications/{id}", "permission": "portal_sync:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get portal publication.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/publications/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/publications/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/publications/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "portal_sync.publication_jobs.list", "title": "List publication sync jobs", "description": "List CRM publication sync jobs.", "method": "GET", "path": "/api/publications/{id}/sync-jobs", "permission": "portal_sync:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List publication sync jobs.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/publications/00000000-0000-4000-8000-000000000000/sync-jobs", "body": null }, "effects": "Reads state through GET /api/publications/{id}/sync-jobs without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/publications/*/sync-jobs", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "real_estate_media.properties.list", "title": "List property media", "description": "List CRM property media.", "method": "GET", "path": "/api/properties/{id}/media", "permission": "properties:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List property media.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/properties/00000000-0000-4000-8000-000000000000/media", "body": null }, "effects": "Reads state through GET /api/properties/{id}/media without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/properties/*/media", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "real_estate_media.properties.create", "title": "Create property media", "description": "Create CRM property media.", "method": "POST", "path": "/api/properties/{id}/media", "permission": "properties:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string" }, "contentType": { "type": "string" }, "fileName": { "type": "string" }, "media_role": { "type": "string" }, "set_primary": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ] } }, "required": [ "id", "contentBase64", "contentType", "fileName" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create property media.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "upload": { "profile": "inline-base64", "contentField": "contentBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 26214400, "acceptedContentTypes": [ "image/*", "video/*" ] } }, "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "contentBase64": "example", "contentType": "example", "fileName": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/properties/00000000-0000-4000-8000-000000000000/media", "body": { "id": "00000000-0000-4000-8000-000000000000", "contentBase64": "example", "contentType": "example", "fileName": "example" } }, "effects": "May change state through POST /api/properties/{id}/media. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/properties/*/media", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "real_estate_media.properties.set_primary", "title": "Set primary property media", "description": "Set primary CRM property media.", "method": "POST", "path": "/api/properties/{propertyId}/media/{mediaId}/primary", "permission": "properties:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "propertyId": { "type": "string", "minLength": 1 }, "mediaId": { "type": "string", "minLength": 1 } }, "required": [ "propertyId", "mediaId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Set primary property media.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "propertyId": "example", "mediaId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/properties/example/media/example/primary", "body": { "propertyId": "example", "mediaId": "example" } }, "effects": "May change state through POST /api/properties/{propertyId}/media/{mediaId}/primary. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/properties/*/media/*/primary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "real_estate_media.properties.delete", "title": "Delete property media", "description": "Delete CRM property media.", "method": "DELETE", "path": "/api/properties/{propertyId}/media/{mediaId}", "permission": "properties:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "propertyId": { "type": "string", "minLength": 1 }, "mediaId": { "type": "string", "minLength": 1 } }, "required": [ "propertyId", "mediaId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete property media.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "propertyId": "example", "mediaId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/properties/example/media/example", "body": null }, "effects": "May change state through DELETE /api/properties/{propertyId}/media/{mediaId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/properties/*/media/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "real_estate_media.listings.list", "title": "List listing media", "description": "List CRM listing media.", "method": "GET", "path": "/api/listings/{id}/media", "permission": "listings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List listing media.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/listings/00000000-0000-4000-8000-000000000000/media", "body": null }, "effects": "Reads state through GET /api/listings/{id}/media without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/listings/*/media", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "real_estate_media.listings.create", "title": "Create listing media", "description": "Create CRM listing media.", "method": "POST", "path": "/api/listings/{id}/media", "permission": "listings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string" }, "contentType": { "type": "string" }, "fileName": { "type": "string" }, "media_role": { "type": "string" }, "set_primary": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ] } }, "required": [ "id", "contentBase64", "contentType", "fileName" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create listing media.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "upload": { "profile": "inline-base64", "contentField": "contentBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 26214400, "acceptedContentTypes": [ "image/*", "video/*" ] } }, "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "contentBase64": "example", "contentType": "example", "fileName": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/listings/00000000-0000-4000-8000-000000000000/media", "body": { "id": "00000000-0000-4000-8000-000000000000", "contentBase64": "example", "contentType": "example", "fileName": "example" } }, "effects": "May change state through POST /api/listings/{id}/media. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/listings/*/media", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "real_estate_media.listings.set_primary", "title": "Set primary listing media", "description": "Set primary CRM listing media.", "method": "POST", "path": "/api/listings/{listingId}/media/{mediaId}/primary", "permission": "listings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "listingId": { "type": "string", "minLength": 1 }, "mediaId": { "type": "string", "minLength": 1 } }, "required": [ "listingId", "mediaId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Set primary listing media.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "listingId": "example", "mediaId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/listings/example/media/example/primary", "body": { "listingId": "example", "mediaId": "example" } }, "effects": "May change state through POST /api/listings/{listingId}/media/{mediaId}/primary. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/listings/*/media/*/primary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "real_estate_media.listings.delete", "title": "Delete listing media", "description": "Delete CRM listing media.", "method": "DELETE", "path": "/api/listings/{listingId}/media/{mediaId}", "permission": "listings:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "listingId": { "type": "string", "minLength": 1 }, "mediaId": { "type": "string", "minLength": 1 } }, "required": [ "listingId", "mediaId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete listing media.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "listingId": "example", "mediaId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/listings/example/media/example", "body": null }, "effects": "May change state through DELETE /api/listings/{listingId}/media/{mediaId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/listings/*/media/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "real_estate_media.get", "title": "Get real estate media", "description": "Get CRM real estate media.", "method": "GET", "path": "/api/real-estate-media/{id}", "permission": "attachments:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get real estate media.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/real-estate-media/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/real-estate-media/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/real-estate-media/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.export", "title": "Export CRM organization data", "description": "Export CRM-owned organization data across all workspaces and storage concerns with credentials redacted and binary objects represented by metadata.", "method": "GET", "path": "/api/organizations/{organizationId}/data", "permission": "privacy:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "organizationId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/example/data", "body": null }, "effects": "Reads state through GET /api/organizations/{organizationId}/data without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.erase", "title": "Erase CRM organization data", "description": "Erase CRM-owned organization data after active business work is closed and exact ERASE confirmation is supplied.", "method": "DELETE", "path": "/api/organizations/{organizationId}/data", "permission": "privacy:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "organizationId", "confirmation" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "organizationId": "example", "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/example/data", "body": null }, "effects": "May change state through DELETE /api/organizations/{organizationId}/data. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget.get", "title": "Get CRM widget", "description": "Get CRM workspace summary widgets.", "method": "GET", "path": "/api/widget", "permission": "contacts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "workspaces.archive", "title": "Archive CRM workspace", "description": "Confirm a CRM workspace holds no records, then ask the platform to archive it. The workspace record itself belongs to Auth.", "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Archive CRM workspace.", "additionalProperties": true }, "method": "DELETE", "path": "/api/crm/workspaces/{workspaceId}", "permission": "workspace:delete", "authorizationMode": "static", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "readOnly": false, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/crm/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/crm/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/crm/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "tickets.list", "title": "List tickets", "description": "List CRM tickets for the selected workspace.", "method": "GET", "path": "/api/tickets", "permission": "contacts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "type": "string" }, "assignee_id": { "type": "string" }, "contact_id": { "type": "string" }, "company_id": { "type": "string" }, "source": { "type": "string" }, "external_thread_id": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "status": "example", "assignee_id": "00000000-0000-4000-8000-000000000000", "contact_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/tickets", "body": null }, "effects": "Reads state through GET /api/tickets without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/tickets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "tickets.get", "title": "Get ticket", "description": "Get a CRM ticket and its messages.", "method": "GET", "path": "/api/tickets/{ticketId}", "permission": "contacts:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string", "minLength": 1 } }, "required": [ "ticketId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "ticketId": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/tickets/example", "body": null }, "effects": "Reads state through GET /api/tickets/{ticketId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/tickets/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "tickets.create", "title": "Create ticket", "description": "Create a CRM ticket with an optional initial message.", "method": "POST", "path": "/api/tickets", "permission": "contacts:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subject": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "priority": { "type": "string" }, "contact_id": { "type": "string" }, "company_id": { "type": "string" }, "assignee_id": { "type": "string" }, "source": { "type": "string" }, "external_thread_id": { "type": "string" }, "message": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1 }, "direction": { "type": "string" }, "sender": { "type": "string" }, "recipients": { "type": "string" }, "message_id": { "type": "string" }, "in_reply_to": { "type": "string" } }, "required": [ "body" ], "additionalProperties": false } }, "required": [ "subject" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "subject": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/tickets", "body": { "subject": "example" } }, "effects": "May change state through POST /api/tickets. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/tickets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "tickets.messages.create", "title": "Add ticket message", "description": "Add a message to a CRM ticket.", "method": "POST", "path": "/api/tickets/{ticketId}/messages", "permission": "contacts:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "direction": { "type": "string" }, "sender": { "type": "string" }, "recipients": { "type": "string" }, "message_id": { "type": "string" }, "in_reply_to": { "type": "string" } }, "required": [ "ticketId", "body" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "ticketId": "example", "body": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/tickets/example/messages", "body": { "ticketId": "example", "body": "example" } }, "effects": "May change state through POST /api/tickets/{ticketId}/messages. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/tickets/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "tickets.email.ingest", "title": "Ingest ticket email", "description": "Ingest an authenticated email event into CRM tickets.", "method": "POST", "path": "/api/tickets/ingest-email", "permission": "contacts:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "from": { "type": "string" }, "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "subject": { "type": "string" }, "body": { "type": "string" }, "messageId": { "type": "string" }, "inReplyTo": { "type": "string" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "from": "example", "to": "example", "subject": "example" }, "cli_example": [ "topolo actions --service topolo-crm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/tickets/ingest-email", "body": { "from": "example", "to": "example", "subject": "example" } }, "effects": "May change state through POST /api/tickets/ingest-email. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/tickets/ingest-email", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 150, "matched_actions": 134, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [ { "key": "* /api/*", "method": "*", "path": "/api/{segment1}", "source": "apps/api/index.ts", "target": "api" }, { "key": "* /docs/*", "method": "*", "path": "/docs/{segment1}", "source": "apps/api/index.ts", "target": "api" } ], "ignored_routes": 14, "configured_exclusions": 9, "configuration_findings": [], "notes": [ "1 manually-declared route(s)" ] }, "runtime_contract_audit": { "status": "verified", "actions": 134, "contracts": 134, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/index.ts" ], "authorization_sources": [ "apps/api/index.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloCRM/topolo.mobile-experience.json", "contract": { "version": "2026-06-29", "status": "approved", "mode": "native_capability", "appId": "app_topolo_crm", "localizationNamespace": "crm", "permissions": [ "crm.contacts.read", "crm.contacts.write", "crm.companies.read", "crm.companies.write", "crm.activities.read" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/contacts", "auth": { "audience": "topolo-crm", "scopes": [ "crm.contacts:read", "crm.contacts:write", "crm.companies:read", "crm.companies:write", "crm.activities:read" ] }, "routes": [ { "path": "/contacts", "apiPath": "/api/contacts", "title": "Contacts", "titleKey": "crm.mobile.routes.contacts.title", "template": "record.list", "dataSource": "crm.contacts.list", "detailRoute": "/contacts/:id", "actions": [ { "id": "crm.contacts.create", "title": "Create contact", "titleKey": "crm.mobile.actions.createContact.title", "type": "record.create", "permission": "crm.contacts.write", "method": "POST", "path": "/api/contacts", "fields": [ { "key": "first", "label": "First name", "labelKey": "crm.contactForm.labels.firstName", "type": "text" }, { "key": "middle_name", "label": "Middle name", "labelKey": "crm.contactForm.labels.middleName", "type": "text" }, { "key": "last", "label": "Last name", "labelKey": "crm.contactForm.labels.lastName", "type": "text" }, { "key": "email", "label": "Email", "labelKey": "crm.contactView.labels.email", "type": "email" }, { "key": "phone", "label": "Phone", "labelKey": "crm.contactForm.labels.phone", "type": "tel" }, { "key": "mobile_phone", "label": "Mobile phone", "labelKey": "crm.contactForm.labels.mobilePhone", "type": "tel" }, { "key": "company", "label": "Company", "labelKey": "crm.contactForm.labels.company", "type": "text" }, { "key": "job_title", "label": "Job title", "labelKey": "crm.contactForm.labels.jobTitle", "type": "text" }, { "key": "employment_role", "label": "Employment role", "labelKey": "crm.contactForm.labels.employmentRole", "type": "text" }, { "key": "seniority", "label": "Seniority", "labelKey": "crm.contactForm.labels.seniority", "type": "text" }, { "key": "department", "label": "Department", "labelKey": "crm.contactForm.labels.department", "type": "text" }, { "key": "lead_status", "label": "Lead status", "labelKey": "crm.contactForm.labels.leadStatus", "type": "text" }, { "key": "lifecycle_stage", "label": "Lifecycle stage", "labelKey": "crm.contactForm.labels.lifecycleStage", "type": "text" }, { "key": "lead_score", "label": "Lead score", "labelKey": "crm.contactForm.labels.leadScore", "type": "number", "min": 0, "max": 100 }, { "key": "contact_accuracy_grade", "label": "Contact accuracy grade", "labelKey": "crm.contactForm.labels.contactAccuracyGrade", "type": "text" }, { "key": "education_level", "label": "Education level", "labelKey": "crm.contactForm.labels.educationLevel", "type": "text" }, { "key": "city", "label": "City", "labelKey": "crm.contactForm.labels.city", "type": "text" }, { "key": "state", "label": "State/Region", "labelKey": "crm.contactForm.labels.stateRegion", "type": "text" }, { "key": "country", "label": "Country", "labelKey": "crm.contactForm.labels.country", "type": "text" }, { "key": "postal_code", "label": "Postal code", "labelKey": "crm.contactForm.labels.postalCode", "type": "text" }, { "key": "address", "label": "Address", "labelKey": "crm.contactForm.labels.address", "type": "textarea" }, { "key": "linkedin_url", "label": "LinkedIn URL", "labelKey": "crm.contactForm.labels.linkedinUrl", "type": "url" }, { "key": "website_url", "label": "Website URL", "labelKey": "crm.contactForm.labels.websiteUrl", "type": "url" }, { "key": "tags", "label": "Tags", "labelKey": "crm.contactForm.labels.tags", "type": "text", "placeholderKey": "crm.contactForm.placeholders.tags", "placeholder": "Comma-separated tags" }, { "key": "external_id", "label": "External ID", "labelKey": "crm.contactForm.labels.externalId", "type": "text", "placeholderKey": "crm.contactForm.placeholders.externalId", "placeholder": "External system ID" } ] }, { "id": "crm.contacts.update", "title": "Update contact", "titleKey": "crm.mobile.actions.updateContact.title", "type": "record.update", "permission": "crm.contacts.write", "method": "PUT", "path": "/api/contacts/:id", "fields": [ { "key": "first", "label": "First name", "labelKey": "crm.contactForm.labels.firstName", "type": "text" }, { "key": "middle_name", "label": "Middle name", "labelKey": "crm.contactForm.labels.middleName", "type": "text" }, { "key": "last", "label": "Last name", "labelKey": "crm.contactForm.labels.lastName", "type": "text" }, { "key": "email", "label": "Email", "labelKey": "crm.contactView.labels.email", "type": "email" }, { "key": "phone", "label": "Phone", "labelKey": "crm.contactForm.labels.phone", "type": "tel" }, { "key": "mobile_phone", "label": "Mobile phone", "labelKey": "crm.contactForm.labels.mobilePhone", "type": "tel" }, { "key": "company", "label": "Company", "labelKey": "crm.contactForm.labels.company", "type": "text" }, { "key": "job_title", "label": "Job title", "labelKey": "crm.contactForm.labels.jobTitle", "type": "text" }, { "key": "employment_role", "label": "Employment role", "labelKey": "crm.contactForm.labels.employmentRole", "type": "text" }, { "key": "seniority", "label": "Seniority", "labelKey": "crm.contactForm.labels.seniority", "type": "text" }, { "key": "department", "label": "Department", "labelKey": "crm.contactForm.labels.department", "type": "text" }, { "key": "lead_status", "label": "Lead status", "labelKey": "crm.contactForm.labels.leadStatus", "type": "text" }, { "key": "lifecycle_stage", "label": "Lifecycle stage", "labelKey": "crm.contactForm.labels.lifecycleStage", "type": "text" }, { "key": "lead_score", "label": "Lead score", "labelKey": "crm.contactForm.labels.leadScore", "type": "number", "min": 0, "max": 100 }, { "key": "contact_accuracy_grade", "label": "Contact accuracy grade", "labelKey": "crm.contactForm.labels.contactAccuracyGrade", "type": "text" }, { "key": "education_level", "label": "Education level", "labelKey": "crm.contactForm.labels.educationLevel", "type": "text" }, { "key": "city", "label": "City", "labelKey": "crm.contactForm.labels.city", "type": "text" }, { "key": "state", "label": "State/Region", "labelKey": "crm.contactForm.labels.stateRegion", "type": "text" }, { "key": "country", "label": "Country", "labelKey": "crm.contactForm.labels.country", "type": "text" }, { "key": "postal_code", "label": "Postal code", "labelKey": "crm.contactForm.labels.postalCode", "type": "text" }, { "key": "address", "label": "Address", "labelKey": "crm.contactForm.labels.address", "type": "textarea" }, { "key": "linkedin_url", "label": "LinkedIn URL", "labelKey": "crm.contactForm.labels.linkedinUrl", "type": "url" }, { "key": "website_url", "label": "Website URL", "labelKey": "crm.contactForm.labels.websiteUrl", "type": "url" }, { "key": "tags", "label": "Tags", "labelKey": "crm.contactForm.labels.tags", "type": "text", "placeholderKey": "crm.contactForm.placeholders.tags", "placeholder": "Comma-separated tags" }, { "key": "external_id", "label": "External ID", "labelKey": "crm.contactForm.labels.externalId", "type": "text", "placeholderKey": "crm.contactForm.placeholders.externalId", "placeholder": "External system ID" } ] }, { "id": "crm.contacts.delete", "title": "Delete contact", "titleKey": "crm.mobile.actions.deleteContact.title", "type": "record.delete", "permission": "crm.contacts.write", "method": "DELETE", "path": "/api/contacts/:id" } ] }, { "path": "/contacts/:id", "apiPath": "/api/contacts/:id", "title": "Contact", "titleKey": "crm.mobile.routes.contactDetail.title", "template": "record.detail", "dataSource": "crm.contacts.detail" }, { "path": "/companies", "apiPath": "/api/companies", "title": "Companies", "titleKey": "crm.mobile.routes.companies.title", "template": "record.list", "dataSource": "crm.companies.list", "detailRoute": "/companies/:id", "actions": [ { "id": "crm.companies.create", "title": "Create company", "type": "record.create", "permission": "crm.companies.write", "method": "POST", "path": "/api/companies", "fields": [ { "key": "name", "label": "Name", "labelKey": "crm.companyView.labels.name", "type": "text", "required": true }, { "key": "external_id", "label": "External ID", "labelKey": "crm.companyForm.labels.externalId", "type": "text" }, { "key": "website", "label": "Website", "labelKey": "crm.companyForm.labels.website", "type": "url" }, { "key": "domain", "label": "Domain", "labelKey": "crm.companyForm.labels.domain", "type": "text" }, { "key": "phone", "label": "Phone", "labelKey": "crm.companyForm.labels.phone", "type": "tel" }, { "key": "fax", "label": "Fax", "labelKey": "crm.companyForm.labels.fax", "type": "tel" }, { "key": "email", "label": "Email", "labelKey": "crm.companyForm.labels.email", "type": "email" }, { "key": "industry", "label": "Industry", "labelKey": "crm.companyForm.labels.industry", "type": "text" }, { "key": "primary_sub_industry", "label": "Primary sub-industry", "labelKey": "crm.companyForm.labels.primarySubIndustry", "type": "text" }, { "key": "size", "label": "Company size", "labelKey": "crm.companyForm.labels.companySize", "type": "select", "options": [ { "value": "startup", "label": "Startup (1-10 employees)" }, { "value": "small", "label": "Small (11-50 employees)" }, { "value": "medium", "label": "Medium (51-200 employees)" }, { "value": "large", "label": "Large (201-1000 employees)" }, { "value": "enterprise", "label": "Enterprise (1000+ employees)" } ] }, { "key": "founded_year", "label": "Founded year", "labelKey": "crm.companyForm.labels.foundedYear", "type": "number", "min": 1800, "max": 3000 }, { "key": "ticker", "label": "Ticker", "labelKey": "crm.companyForm.labels.ticker", "type": "text" }, { "key": "employee_count", "label": "Employee count", "labelKey": "crm.companyForm.labels.employeeCount", "type": "number", "min": 0 }, { "key": "employee_range", "label": "Employee range", "labelKey": "crm.companyForm.labels.employeeRange", "type": "text" }, { "key": "revenue_range", "label": "Revenue range", "labelKey": "crm.companyForm.labels.revenueRange", "type": "text" }, { "key": "description", "label": "Description", "labelKey": "crm.companyForm.labels.description", "type": "textarea" }, { "key": "linkedin_url", "label": "LinkedIn URL", "labelKey": "crm.companyForm.labels.linkedInUrl", "type": "url" }, { "key": "external_profile_url", "label": "External profile URL", "labelKey": "crm.companyForm.labels.externalProfileUrl", "type": "url" }, { "key": "address", "label": "Address", "labelKey": "crm.companyForm.labels.address", "type": "textarea" }, { "key": "city", "label": "City", "labelKey": "crm.companyForm.labels.city", "type": "text" }, { "key": "state", "label": "State / Region", "labelKey": "crm.companyForm.labels.stateRegion", "type": "text" }, { "key": "postal_code", "label": "Postal code", "labelKey": "crm.companyForm.labels.postalCode", "type": "text" }, { "key": "country", "label": "Country", "labelKey": "crm.companyForm.labels.country", "type": "text" }, { "key": "logo_url", "label": "Logo URL", "labelKey": "crm.companyForm.labels.logoUrl", "type": "url" } ], "titleKey": "crm.mobile.actions.createCompany.title" }, { "id": "crm.companies.update", "title": "Update company", "type": "record.update", "permission": "crm.companies.write", "method": "PUT", "path": "/api/companies/:id", "fields": [ { "key": "name", "label": "Name", "labelKey": "crm.companyView.labels.name", "type": "text" }, { "key": "external_id", "label": "External ID", "labelKey": "crm.companyForm.labels.externalId", "type": "text" }, { "key": "website", "label": "Website", "labelKey": "crm.companyForm.labels.website", "type": "url" }, { "key": "domain", "label": "Domain", "labelKey": "crm.companyForm.labels.domain", "type": "text" }, { "key": "phone", "label": "Phone", "labelKey": "crm.companyForm.labels.phone", "type": "tel" }, { "key": "fax", "label": "Fax", "labelKey": "crm.companyForm.labels.fax", "type": "tel" }, { "key": "email", "label": "Email", "labelKey": "crm.companyForm.labels.email", "type": "email" }, { "key": "industry", "label": "Industry", "labelKey": "crm.companyForm.labels.industry", "type": "text" }, { "key": "primary_sub_industry", "label": "Primary sub-industry", "labelKey": "crm.companyForm.labels.primarySubIndustry", "type": "text" }, { "key": "size", "label": "Company size", "labelKey": "crm.companyForm.labels.companySize", "type": "select", "options": [ { "value": "startup", "label": "Startup (1-10 employees)" }, { "value": "small", "label": "Small (11-50 employees)" }, { "value": "medium", "label": "Medium (51-200 employees)" }, { "value": "large", "label": "Large (201-1000 employees)" }, { "value": "enterprise", "label": "Enterprise (1000+ employees)" } ] }, { "key": "founded_year", "label": "Founded year", "labelKey": "crm.companyForm.labels.foundedYear", "type": "number", "min": 1800, "max": 3000 }, { "key": "ticker", "label": "Ticker", "labelKey": "crm.companyForm.labels.ticker", "type": "text" }, { "key": "employee_count", "label": "Employee count", "labelKey": "crm.companyForm.labels.employeeCount", "type": "number", "min": 0 }, { "key": "employee_range", "label": "Employee range", "labelKey": "crm.companyForm.labels.employeeRange", "type": "text" }, { "key": "revenue_range", "label": "Revenue range", "labelKey": "crm.companyForm.labels.revenueRange", "type": "text" }, { "key": "description", "label": "Description", "labelKey": "crm.companyForm.labels.description", "type": "textarea" }, { "key": "linkedin_url", "label": "LinkedIn URL", "labelKey": "crm.companyForm.labels.linkedInUrl", "type": "url" }, { "key": "external_profile_url", "label": "External profile URL", "labelKey": "crm.companyForm.labels.externalProfileUrl", "type": "url" }, { "key": "address", "label": "Address", "labelKey": "crm.companyForm.labels.address", "type": "textarea" }, { "key": "city", "label": "City", "labelKey": "crm.companyForm.labels.city", "type": "text" }, { "key": "state", "label": "State / Region", "labelKey": "crm.companyForm.labels.stateRegion", "type": "text" }, { "key": "postal_code", "label": "Postal code", "labelKey": "crm.companyForm.labels.postalCode", "type": "text" }, { "key": "country", "label": "Country", "labelKey": "crm.companyForm.labels.country", "type": "text" }, { "key": "logo_url", "label": "Logo URL", "labelKey": "crm.companyForm.labels.logoUrl", "type": "url" } ], "titleKey": "crm.mobile.actions.updateCompany.title" }, { "id": "crm.companies.delete", "title": "Delete company", "type": "record.delete", "permission": "crm.companies.write", "method": "DELETE", "path": "/api/companies/:id", "titleKey": "crm.mobile.actions.deleteCompany.title" } ] }, { "path": "/companies/:id", "apiPath": "/api/companies/:id", "title": "Company", "titleKey": "crm.mobile.routes.companyDetail.title", "template": "record.detail", "dataSource": "crm.companies.detail" }, { "path": "/contacts/:id/activity", "apiPath": "/api/pipeline/:id/history", "title": "Activity", "titleKey": "crm.mobile.routes.activity.title", "template": "activity.timeline", "dataSource": "crm.activities.timeline" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "OPTIONS", "path": "*", "source_path": "apps/TopoloCRM/apps/api/index.ts" }, { "method": "GET", "path": "/warmup", "source_path": "apps/TopoloCRM/apps/api/index.ts" }, { "method": "GET", "path": "/health", "source_path": "apps/TopoloCRM/apps/api/index.ts" }, { "method": "GET", "path": "/api/health", "source_path": "apps/TopoloCRM/apps/api/index.ts" }, { "method": "GET", "path": "/api/widget", "source_path": "apps/TopoloCRM/apps/api/index.ts" }, { "method": "GET", "path": "/api", "source_path": "apps/TopoloCRM/apps/api/index.ts" }, { "method": "ALL", "path": "*", "source_path": "apps/TopoloCRM/apps/api/index.ts" }, { "method": "LITERAL", "path": "/health", "source_path": "apps/TopoloCRM/apps/api/index.ts" } ], "ui_routes": [ { "path": "/tasks/${task.id}", "source_path": "apps/TopoloCRM/apps/api/lib/crm-notifications.ts" }, { "path": "/transactions/${milestone.transaction_id}", "source_path": "apps/TopoloCRM/apps/api/lib/crm-notifications.ts" }, { "path": "/offers/${offerId}", "source_path": "apps/TopoloCRM/apps/api/routes/offers.ts" }, { "path": "/offers/${id}", "source_path": "apps/TopoloCRM/apps/api/routes/offers.ts" }, { "path": "/portal-leads/${leadEventId}", "source_path": "apps/TopoloCRM/apps/api/routes/portal-leads.ts" }, { "path": "/listings/${listingId}", "source_path": "apps/TopoloCRM/apps/api/routes/portal-sync.ts" }, { "path": "/showings/${showingId}", "source_path": "apps/TopoloCRM/apps/api/routes/showings.ts" }, { "path": "/tasks/${taskId}", "source_path": "apps/TopoloCRM/apps/api/routes/tasks.ts" }, { "path": "/tasks/${id}", "source_path": "apps/TopoloCRM/apps/api/routes/tasks.ts" }, { "path": "/inbox", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/contacts", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/contacts/:contactId", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/companies", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/companies/:companyId", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/deals", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/deals/:dealId", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/import", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/pipeline", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/pipeline/:pipelineId", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/tasks", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/dashboard", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/properties", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/properties/:propertyId", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/listings", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/listings/:listingId", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/showings", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/offers", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/transactions", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/transactions/:transactionId", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/commissions", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/portal-connections", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/portal-leads", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/settings", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/settings/:section", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloCRM/apps/web/src/App.tsx" }, { "path": "/${path}", "source_path": "apps/TopoloCRM/apps/web/src/utils/api/real-estate-api.ts" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "internal/apps/crm", "applications/crm" ], "present_paths": [ "internal/apps/crm", "applications/crm" ], "missing_paths": [], "human_reference": "/systems/topolo-crm", "machine_reference": "/machine/systems/topolo-crm.json", "action_examples": 134, "action_schemas": 134 }, "source_findings": [ { "type": "uncatalogued_routes", "source_path": "apps/TopoloCRM/topolo.app.json", "detail": [ { "key": "* /api/*", "method": "*", "path": "/api/{segment1}", "source": "apps/api/index.ts", "target": "api" }, { "key": "* /docs/*", "method": "*", "path": "/docs/{segment1}", "source": "apps/api/index.ts", "target": "api" } ] } ] }, "topolo-design": { "id": "topolo-design", "name": "Topolo Design", "slug": "topolo-design", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloDesign" ], "source_revisions": [ { "source_path": "apps/TopoloDesign", "repository": "apps/TopoloDesign", "revision": "b07fc4d973a6c3b8285bd2f506e830f88544e0b8", "ref": "origin/staging" } ], "source_counts": { "source_files": 78, "test_files": 57, "test_cases": 0, "migration_files": 12, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 38, "mobile_contracts": 0, "notifications": 1, "package_manifests": 1, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloDesign/topolo.app.json", "service_slug": "topolo-design", "name": "topolo-design", "app_id": "app_topolo_design", "compatibility_date": "2026-05-05", "primary_target": null, "environments": [ "development", "production", "staging" ], "targets": [ { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/worker.ts", "worker_name": "topolo-design-api", "subdomain": null, "healthcheck_path": "/api/health", "variable_names": [ "AUTH_BASE_URL", "DESIGN_APP_URL", "LIBRARY_OWNER_ORGANIZATION_ID", "LIBRARY_OWNER_WORKSPACE_ID", "NEXUS_GATEWAY_URL", "RENDER_SERVICE_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "DESIGN_CORE_DB", "target": null }, { "kind": "r2", "binding": "APP_ASSETS", "target": null }, { "kind": "services", "binding": "BRAND_API", "target": null } ] }, { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-design", "subdomain": "design", "healthcheck_path": "/api/health", "variable_names": [ "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null } ] } ], "notifications": [ "design.export.ready" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_design", "events": [ { "type": "design.export.ready", "version": 1, "description": "A persisted Design export reached ready state after its content was stored.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "project_id", "export_id", "format" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "priority": { "enum": [ "low", "normal", "high", "urgent" ] }, "severity": { "enum": [ "info", "success", "warning", "critical" ] }, "category": { "type": "string" }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "project_id": { "type": "string", "minLength": 1 }, "export_id": { "type": "string", "minLength": 1 }, "format": { "enum": [ "svg", "png", "jpeg", "mp4" ] } }, "additionalProperties": false }, "examples": [ { "title": "Export ready: Launch graphic", "body": "Your PNG export is ready.", "surface": "action", "priority": "normal", "severity": "success", "category": "design", "object_type": "design_export", "object_id": "design_export_123", "cta_url": "https://design.topolo.app/app/projects/design_123", "cta_label": "Open design", "occurred_at": "2026-08-10T00:00:00.000Z", "project_id": "design_123", "export_id": "design_export_123", "format": "png" } ], "dataClassification": "internal", "recipients": { "modes": [ "workspace_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^design:export:ready:" }, "sensitiveFields": [] } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for Design.", "method": "GET", "path": "/api/widget", "permission": "workspace:read", "readOnly": true, "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" }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": {} } } }, "required": [ "success", "widgets" ], "additionalProperties": {} }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=widget.get", "resource": { "kind": "widget", "idPath": "$.id" }, "effects": [ "Reads widget data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected widget context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for widget.get." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/widget", "body": null }, "effects": "Reads widget data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected widget context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=widget.get", "resource": { "kind": "widget", "idPath": "$.id" }, "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 workspace bootstrap", "description": "Get the signed Design workspace bootstrap.", "method": "GET", "path": "/api/bootstrap", "permission": "workspace:read", "readOnly": true, "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": { "user": {}, "organization": {} }, "required": [ "user", "organization" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=workspace.bootstrap", "resource": { "kind": "workspace", "idPath": "$.workspace.id" }, "effects": [ "Reads the signed Design workspace bootstrap without changing workspace state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Use the returned workspace id only in the current credential context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for workspace.bootstrap." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata", "nextActionIds": [ "app_topolo_auth.workspaces.list", "app_topolo_auth.workspaces.create", "app_topolo_auth.workspaces.rename", "app_topolo_auth.workspaces.default.set" ] }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/bootstrap", "body": null }, "effects": "Reads the signed Design workspace bootstrap without changing workspace state.", "verification": [ "Use the returned workspace id only in the current credential context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=workspace.bootstrap", "resource": { "kind": "workspace", "idPath": "$.workspace.id" }, "next_action_ids": [ "app_topolo_auth.workspaces.list", "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/bootstrap", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "brands.list", "title": "List Brand options", "description": "List accessible published Brand kits available for governed design creation.", "method": "GET", "path": "/api/brand-options", "permission": "brands:read", "readOnly": true, "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": { "available": { "type": "boolean" }, "brands": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "currentVersionId": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "currentVersionId" ], "additionalProperties": false } } }, "required": [ "available", "brands" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=brands.list", "resource": { "kind": "brand", "idPath": "$.brands[].id" }, "effects": [ "Reads brand data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission brands:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected brand context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for brands.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/brand-options", "body": null }, "effects": "Reads brand data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected brand context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission brands:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=brands.list", "resource": { "kind": "brand", "idPath": "$.brands[].id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/brand-options", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "folders.list", "title": "List project folders", "description": "List workspace folders used to catalogue Design projects.", "method": "GET", "path": "/api/folders", "permission": "folders:read", "readOnly": true, "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": { "folders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "folders" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=folders.list", "resource": { "kind": "design_folder", "idPath": "$.folders[].id" }, "effects": [ "Reads design_folder data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission folders:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected design_folder context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for folders.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/folders", "body": null }, "effects": "Reads design_folder data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected design_folder context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission folders:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=folders.list", "resource": { "kind": "design_folder", "idPath": "$.folders[].id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/folders", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "folders.create", "title": "Create project folder", "description": "Create a workspace folder for Design projects.", "method": "POST", "path": "/api/folders", "permission": "folders:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "name" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folder": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "folder" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=folders.create", "resource": { "kind": "design_folder", "idPath": "$.folder.id" }, "effects": [ "Creates one workspace-scoped folder for cataloguing Design projects." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission folders:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.folders.list and confirm the returned folder appears once." ], "examples": [ { "input": { "name": "Launch campaign" }, "expected": "A response matching the published outputSchema for folders.create." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_design.folders.delete", "instructions": "Invoke app_topolo_design.folders.delete with the created folder id after confirming the rollback; any projects already filed into it move to Unfiled." }, "contractSource": "design-action-metadata", "rollbackActionId": "app_topolo_design.folders.delete" }, "documentation": { "example_input": { "name": "Launch campaign" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/folders", "body": { "name": "Launch campaign" } }, "effects": "Creates one workspace-scoped folder for cataloguing Design projects.", "verification": [ "Call app_topolo_design.folders.list and confirm the returned folder appears once." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_design.folders.delete", "instructions": "Invoke app_topolo_design.folders.delete with the created folder id after confirming the rollback; any projects already filed into it move to Unfiled." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission folders:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=folders.create", "resource": { "kind": "design_folder", "idPath": "$.folder.id" }, "next_action_ids": [], "rollback_action_id": "app_topolo_design.folders.delete" }, "implementation": { "status": "implemented", "route_key": "POST /api/folders", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "folders.update", "title": "Rename project folder", "description": "Rename a workspace folder without changing its projects.", "method": "PATCH", "path": "/api/folders/{folderId}", "permission": "folders:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folderId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "folderId", "name" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folder": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "folder" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=folders.update", "resource": { "kind": "design_folder", "idPath": "$.folder.id" }, "effects": [ "Rename a workspace folder without changing its projects." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission folders:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected design_folder context." ], "examples": [ { "input": { "folderId": "design_folder_123", "name": "Product launch" }, "expected": "A response matching the published outputSchema for folders.update." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_design.folders.update", "requiresSnapshot": true, "instructions": "Capture the folder name before the call, then invoke this action with the captured name to restore it." }, "contractSource": "design-action-metadata" }, "documentation": { "example_input": { "folderId": "design_folder_123", "name": "Product launch" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/folders/design_folder_123", "body": { "folderId": "design_folder_123", "name": "Product launch" } }, "effects": "Rename a workspace folder without changing its projects.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected design_folder context." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_design.folders.update", "requiresSnapshot": true, "instructions": "Capture the folder name before the call, then invoke this action with the captured name to restore it." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission folders:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=folders.update", "resource": { "kind": "design_folder", "idPath": "$.folder.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "declared_unserved", "route_key": "PATCH /api/folders/*", "evidence": "No matching served route was extracted from canonical staging source." } }, { "name": "folders.delete", "title": "Delete project folder", "description": "Delete a folder and move its projects to Unfiled.", "method": "DELETE", "path": "/api/folders/{folderId}", "permission": "folders:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folderId": { "type": "string", "minLength": 1 } }, "required": [ "folderId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folder": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "folder" ], "additionalProperties": false }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=folders.delete", "resource": { "kind": "design_folder", "idPath": "$.folder.id" }, "effects": [ "Deletes one folder and moves its projects to the unfiled collection without deleting projects." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission folders:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.folders.list and confirm the folder is absent, then list projects and confirm their folderId is null." ], "examples": [ { "input": { "folderId": "design_folder_123" }, "expected": "A response matching the published outputSchema for folders.delete." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Projects are preserved in Unfiled; recreating the folder does not restore their prior filing, so confirm before calling." }, "contractSource": "design-action-metadata" }, "documentation": { "example_input": { "folderId": "design_folder_123" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/folders/design_folder_123", "body": null }, "effects": "Deletes one folder and moves its projects to the unfiled collection without deleting projects.", "verification": [ "Call app_topolo_design.folders.list and confirm the folder is absent, then list projects and confirm their folderId is null." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Projects are preserved in Unfiled; recreating the folder does not restore their prior filing, so confirm before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission folders:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=folders.delete", "resource": { "kind": "design_folder", "idPath": "$.folder.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "declared_unserved", "route_key": "DELETE /api/folders/*", "evidence": "No matching served route was extracted from canonical staging source." } }, { "name": "projects.list", "title": "List design projects", "description": "List active, archived, or all design projects in the selected workspace.", "method": "GET", "path": "/api/projects", "permission": "projects:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "default": "active", "type": "string", "enum": [ "active", "archived", "all" ] } }, "required": [ "scope" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 }, "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "pageCount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "createdAt", "updatedAt", "width", "height", "pageCount" ], "additionalProperties": false } } }, "required": [ "projects" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.list", "resource": { "kind": "design_project", "idPath": "$.projects[].id" }, "effects": [ "Reads design_project data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission projects:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected design_project context." ], "examples": [ { "input": { "scope": "active" }, "expected": "A response matching the published outputSchema for projects.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata" }, "documentation": { "example_input": { "scope": "active" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/projects", "body": null }, "effects": "Reads design_project data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected design_project context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission projects:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.list", "resource": { "kind": "design_project", "idPath": "$.projects[].id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/projects", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.get", "title": "Get design project", "description": "Get one editable, version-locked design project.", "method": "GET", "path": "/api/projects/{projectId}", "permission": "projects:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 } }, "required": [ "projectId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "document", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.get", "resource": { "kind": "design_project", "idPath": "$.project.id" }, "effects": [ "Reads design_project data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission projects:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected design_project context." ], "examples": [ { "input": { "projectId": "design_123" }, "expected": "A response matching the published outputSchema for projects.get." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata" }, "documentation": { "example_input": { "projectId": "design_123" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/projects/design_123", "body": null }, "effects": "Reads design_project data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected design_project context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission projects:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.get", "resource": { "kind": "design_project", "idPath": "$.project.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/projects/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.create", "title": "Create design project", "description": "Create an editable composition with an optional published Brand version.", "method": "POST", "path": "/api/projects", "permission": "projects:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandKitId": { "type": "string", "minLength": 1 }, "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "starter": { "default": "blank", "type": "string", "enum": [ "blank", "brand" ] } }, "required": [ "name", "starter" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "document", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.create", "resource": { "kind": "design_project", "idPath": "$.project.id" }, "effects": [ "Creates one editable design project, optionally pinned to an accessible published Brand version." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission projects:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.projects.get with the returned project id and confirm its document and optional Brand provenance." ], "examples": [ { "input": { "name": "Launch banner", "width": 1080, "height": 1080, "starter": "blank" }, "expected": "A response matching the published outputSchema for projects.create." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_design.projects.archive", "instructions": "Invoke app_topolo_design.projects.archive with the created project id after confirming the rollback." }, "contractSource": "design-action-metadata", "rollbackActionId": "app_topolo_design.projects.archive", "nextActionIds": [ "app_topolo_design.projects.get", "app_topolo_design.exports.create" ] }, "documentation": { "example_input": { "name": "Launch banner", "width": 1080, "height": 1080, "starter": "blank" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects", "body": { "name": "Launch banner", "width": 1080, "height": 1080, "starter": "blank" } }, "effects": "Creates one editable design project, optionally pinned to an accessible published Brand version.", "verification": [ "Call app_topolo_design.projects.get with the returned project id and confirm its document and optional Brand provenance." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_design.projects.archive", "instructions": "Invoke app_topolo_design.projects.archive with the created project id after confirming the rollback." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission projects:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.create", "resource": { "kind": "design_project", "idPath": "$.project.id" }, "next_action_ids": [ "app_topolo_design.projects.get", "app_topolo_design.exports.create" ], "rollback_action_id": "app_topolo_design.projects.archive" }, "implementation": { "status": "implemented", "route_key": "POST /api/projects", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.copy", "title": "Copy design project", "description": "Create an independent editable draft from an existing project while preserving its document and Brand provenance.", "method": "POST", "path": "/api/projects/{projectId}/copy", "permission": "projects:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "projectId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "document", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.copy", "resource": { "kind": "design_project", "idPath": "$.project.id" }, "effects": [ "Creates one independent draft project from the source document, preserving its pages, layout, assets, and published Brand provenance without copying exports." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission projects:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.projects.get with the returned project id and confirm the document and Brand provenance match the source project." ], "examples": [ { "input": { "projectId": "design_123", "name": "Launch banner variation" }, "expected": "A response matching the published outputSchema for projects.copy." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_design.projects.archive", "instructions": "Invoke app_topolo_design.projects.archive with the copied project id after confirming the rollback." }, "contractSource": "design-action-metadata", "rollbackActionId": "app_topolo_design.projects.archive", "nextActionIds": [ "app_topolo_design.projects.get", "app_topolo_design.projects.update", "app_topolo_design.exports.create" ] }, "documentation": { "example_input": { "projectId": "design_123", "name": "Launch banner variation" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects/design_123/copy", "body": { "projectId": "design_123", "name": "Launch banner variation" } }, "effects": "Creates one independent draft project from the source document, preserving its pages, layout, assets, and published Brand provenance without copying exports.", "verification": [ "Call app_topolo_design.projects.get with the returned project id and confirm the document and Brand provenance match the source project." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_design.projects.archive", "instructions": "Invoke app_topolo_design.projects.archive with the copied project id after confirming the rollback." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission projects:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.copy", "resource": { "kind": "design_project", "idPath": "$.project.id" }, "next_action_ids": [ "app_topolo_design.projects.get", "app_topolo_design.projects.update", "app_topolo_design.exports.create" ], "rollback_action_id": "app_topolo_design.projects.archive" }, "implementation": { "status": "implemented", "route_key": "POST /api/projects/*/copy", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.update", "title": "Update design project", "description": "Rename a project and/or replace its canvas document whole. Read the document with projects.get, modify it, and send the complete result back.", "method": "PATCH", "path": "/api/projects/{projectId}", "permission": "projects:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." } }, "required": [ "projectId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "document", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.update", "resource": { "kind": "design_project", "idPath": "$.project.id" }, "effects": [ "Renames, files, or stars one design project and/or replaces its entire canvas document with the provided one." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission projects:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.projects.get and confirm the returned name, folder, star, and document match what was sent." ], "examples": [ { "input": { "projectId": "design_123", "name": "Updated launch banner", "document": { "schemaVersion": 5, "brand": null, "fontSources": [], "pages": [ { "id": "page_1", "name": "Page 1", "canvas": { "width": 1080, "height": 1080, "background": "#ffffff" }, "elements": [ { "id": "el_headline", "name": "Headline", "purpose": "headline", "type": "text", "frame": { "x": 80, "y": 120, "width": 920, "height": 200, "rotation": 0 }, "opacity": 1, "hidden": false, "locked": false, "text": "Launch day", "style": { "fontFamily": "Inter", "fontSize": 96, "minFontSize": 48, "maxFontSize": 96, "autoFit": true, "fontWeight": 700, "lineHeight": 1.1, "letterSpacing": 0, "color": "#111111", "textAlign": "center", "verticalAlign": "middle" } }, { "id": "el_accent", "name": "Accent bar", "purpose": "decoration", "type": "shape", "kind": "rectangle", "frame": { "x": 80, "y": 360, "width": 920, "height": 12, "rotation": 0 }, "opacity": 1, "hidden": false, "locked": false, "style": { "fill": "#3355ff", "stroke": "#3355ff", "strokeWidth": 0, "cornerRadius": 6 } } ], "animation": { "durationMs": 3000, "fps": 24, "motions": [ { "elementId": "el_headline", "preset": "fade", "startMs": 0, "durationMs": 600, "easing": "ease-out" } ] } } ], "exportSettings": { "format": "png", "scale": 1, "quality": 0.92, "transparent": false } } }, "expected": "A response matching the published outputSchema for projects.update." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_design.projects.update", "requiresSnapshot": true, "instructions": "Capture the current project document and metadata before the call, then invoke this action with the captured values to restore them." }, "contractSource": "design-action-metadata", "nextActionIds": [ "app_topolo_design.projects.get", "app_topolo_design.exports.estimate", "app_topolo_design.exports.create" ] }, "documentation": { "example_input": { "projectId": "design_123", "name": "Updated launch banner", "document": { "schemaVersion": 5, "brand": null, "fontSources": [], "pages": [ { "id": "page_1", "name": "Page 1", "canvas": { "width": 1080, "height": 1080, "background": "#ffffff" }, "elements": [ { "id": "el_headline", "name": "Headline", "purpose": "headline", "type": "text", "frame": { "x": 80, "y": 120, "width": 920, "height": 200, "rotation": 0 }, "opacity": 1, "hidden": false, "locked": false, "text": "Launch day", "style": { "fontFamily": "Inter", "fontSize": 96, "minFontSize": 48, "maxFontSize": 96, "autoFit": true, "fontWeight": 700, "lineHeight": 1.1, "letterSpacing": 0, "color": "#111111", "textAlign": "center", "verticalAlign": "middle" } }, { "id": "el_accent", "name": "Accent bar", "purpose": "decoration", "type": "shape", "kind": "rectangle", "frame": { "x": 80, "y": 360, "width": 920, "height": 12, "rotation": 0 }, "opacity": 1, "hidden": false, "locked": false, "style": { "fill": "#3355ff", "stroke": "#3355ff", "strokeWidth": 0, "cornerRadius": 6 } } ], "animation": { "durationMs": 3000, "fps": 24, "motions": [ { "elementId": "el_headline", "preset": "fade", "startMs": 0, "durationMs": 600, "easing": "ease-out" } ] } } ], "exportSettings": { "format": "png", "scale": 1, "quality": 0.92, "transparent": false } } }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/projects/design_123", "body": { "projectId": "design_123", "name": "Updated launch banner", "document": { "schemaVersion": 5, "brand": null, "fontSources": [], "pages": [ { "id": "page_1", "name": "Page 1", "canvas": { "width": 1080, "height": 1080, "background": "#ffffff" }, "elements": [ { "id": "el_headline", "name": "Headline", "purpose": "headline", "type": "text", "frame": { "x": 80, "y": 120, "width": 920, "height": 200, "rotation": 0 }, "opacity": 1, "hidden": false, "locked": false, "text": "Launch day", "style": { "fontFamily": "Inter", "fontSize": 96, "minFontSize": 48, "maxFontSize": 96, "autoFit": true, "fontWeight": 700, "lineHeight": 1.1, "letterSpacing": 0, "color": "#111111", "textAlign": "center", "verticalAlign": "middle" } }, { "id": "el_accent", "name": "Accent bar", "purpose": "decoration", "type": "shape", "kind": "rectangle", "frame": { "x": 80, "y": 360, "width": 920, "height": 12, "rotation": 0 }, "opacity": 1, "hidden": false, "locked": false, "style": { "fill": "#3355ff", "stroke": "#3355ff", "strokeWidth": 0, "cornerRadius": 6 } } ], "animation": { "durationMs": 3000, "fps": 24, "motions": [ { "elementId": "el_headline", "preset": "fade", "startMs": 0, "durationMs": 600, "easing": "ease-out" } ] } } ], "exportSettings": { "format": "png", "scale": 1, "quality": 0.92, "transparent": false } } } }, "effects": "Renames, files, or stars one design project and/or replaces its entire canvas document with the provided one.", "verification": [ "Call app_topolo_design.projects.get and confirm the returned name, folder, star, and document match what was sent." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_design.projects.update", "requiresSnapshot": true, "instructions": "Capture the current project document and metadata before the call, then invoke this action with the captured values to restore them." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission projects:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.update", "resource": { "kind": "design_project", "idPath": "$.project.id" }, "next_action_ids": [ "app_topolo_design.projects.get", "app_topolo_design.exports.estimate", "app_topolo_design.exports.create" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/projects/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.archive", "title": "Archive design project", "description": "Archive a design project without deleting its provenance or exports.", "method": "DELETE", "path": "/api/projects/{projectId}", "permission": "projects:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 } }, "required": [ "projectId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "document", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.archive", "resource": { "kind": "design_project", "idPath": "$.project.id" }, "effects": [ "Archives one design project so it no longer appears in the active project list." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission projects:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.projects.get and confirm the returned project status is archived." ], "examples": [ { "input": { "projectId": "design_123" }, "expected": "A response matching the published outputSchema for projects.archive." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_design.projects.restore", "instructions": "Invoke app_topolo_design.projects.restore with the archived project id to return it to the workspace library." }, "contractSource": "design-action-metadata", "rollbackActionId": "app_topolo_design.projects.restore" }, "documentation": { "example_input": { "projectId": "design_123" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/projects/design_123", "body": null }, "effects": "Archives one design project so it no longer appears in the active project list.", "verification": [ "Call app_topolo_design.projects.get and confirm the returned project status is archived." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_design.projects.restore", "instructions": "Invoke app_topolo_design.projects.restore with the archived project id to return it to the workspace library." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission projects:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.archive", "resource": { "kind": "design_project", "idPath": "$.project.id" }, "next_action_ids": [], "rollback_action_id": "app_topolo_design.projects.restore" }, "implementation": { "status": "implemented", "route_key": "DELETE /api/projects/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.delete", "title": "Delete an archived project", "description": "Permanently remove one archived design project and every export taken from it. Refused unless the project is already archived.", "method": "DELETE", "path": "/api/projects/{projectId}/delete", "permission": "projects:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 } }, "required": [ "projectId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "string" }, "exports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "deleted", "exports" ], "additionalProperties": false }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.delete", "resource": { "kind": "design_project", "idPath": "$.deleted" }, "effects": [ "Permanently removes one archived design project and every export taken from it, including their stored objects.", "Refused with 409 unless the project is already archived." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission projects:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.projects.list with scope archived and confirm the project id is absent." ], "examples": [ { "input": { "projectId": "design_launch" }, "expected": "A response matching the published outputSchema for projects.delete." } ], "recovery": { "mode": "irreversible", "instructions": "Deletion is permanent. Export anything worth keeping before calling, and archive rather than delete when in doubt." }, "contractSource": "design-action-metadata" }, "documentation": { "example_input": { "projectId": "design_launch" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/projects/design_launch/delete", "body": null }, "effects": "Permanently removes one archived design project and every export taken from it, including their stored objects. Refused with 409 unless the project is already archived.", "verification": [ "Call app_topolo_design.projects.list with scope archived and confirm the project id is absent." ], "recovery": [ { "mode": "irreversible", "instructions": "Deletion is permanent. Export anything worth keeping before calling, and archive rather than delete when in doubt." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission projects:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.delete", "resource": { "kind": "design_project", "idPath": "$.deleted" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/projects/*/delete", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.restore", "title": "Restore design project", "description": "Restore an archived design project to the editable draft list.", "method": "POST", "path": "/api/projects/{projectId}/restore", "permission": "projects:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 } }, "required": [ "projectId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "document", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.restore", "resource": { "kind": "design_project", "idPath": "$.project.id" }, "effects": [ "Restores one archived design project to draft status." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission projects:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.projects.get and confirm the returned project status is draft." ], "examples": [ { "input": { "projectId": "design_123" }, "expected": "A response matching the published outputSchema for projects.restore." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_design.projects.archive", "instructions": "Invoke app_topolo_design.projects.archive with the restored project id to archive it again." }, "contractSource": "design-action-metadata", "rollbackActionId": "app_topolo_design.projects.archive" }, "documentation": { "example_input": { "projectId": "design_123" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects/design_123/restore", "body": { "projectId": "design_123" } }, "effects": "Restores one archived design project to draft status.", "verification": [ "Call app_topolo_design.projects.get and confirm the returned project status is draft." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_design.projects.archive", "instructions": "Invoke app_topolo_design.projects.archive with the restored project id to archive it again." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission projects:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=projects.restore", "resource": { "kind": "design_project", "idPath": "$.project.id" }, "next_action_ids": [], "rollback_action_id": "app_topolo_design.projects.archive" }, "implementation": { "status": "implemented", "route_key": "POST /api/projects/*/restore", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "exports.list", "title": "List design exports", "description": "List ready, pending, or all generated Design exports stored for the selected workspace.", "method": "GET", "path": "/api/exports", "permission": "exports:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "default": "ready", "type": "string", "enum": [ "ready", "pending", "all" ] } }, "required": [ "status" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "video/mp4" ] }, "width": { "type": "integer", "minimum": 320, "maximum": 4096 }, "height": { "type": "integer", "minimum": 320, "maximum": 4096 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 500, "maximum": 30000 }, { "type": "null" } ] }, "fps": { "anyOf": [ { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, { "type": "null" } ] }, "storageKey": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "minLength": 1 }, "estimatedByteSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byteSize": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "ready" ] }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "projectId", "format", "mimeType", "width", "height", "quality", "durationMs", "fps", "storageKey", "altText", "estimatedByteSize", "byteSize", "status", "createdAt" ], "additionalProperties": false } } }, "required": [ "exports" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=exports.list", "resource": { "kind": "design_export", "idPath": "$.exports[].id" }, "effects": [ "Lists immutable Design media records stored for the selected workspace without downloading their content." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission exports:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Confirm every returned export belongs to the selected workspace and use exports.get before downloading content." ], "examples": [ { "input": { "status": "ready" }, "expected": "A response matching the published outputSchema for exports.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata", "nextActionIds": [ "app_topolo_design.exports.get" ] }, "documentation": { "example_input": { "status": "ready" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/exports", "body": null }, "effects": "Lists immutable Design media records stored for the selected workspace without downloading their content.", "verification": [ "Confirm every returned export belongs to the selected workspace and use exports.get before downloading content." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission exports:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=exports.list", "resource": { "kind": "design_export", "idPath": "$.exports[].id" }, "next_action_ids": [ "app_topolo_design.exports.get" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/exports", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "exports.estimate", "title": "Estimate design export size", "description": "Estimate the output size for a static or animated Design export without creating it.", "method": "POST", "path": "/api/projects/{projectId}/exports/estimate", "permission": "exports:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "width": { "type": "integer", "minimum": 320, "maximum": 4096 }, "height": { "type": "integer", "minimum": 320, "maximum": 4096 }, "quality": { "default": 0.92, "type": "number", "minimum": 0.1, "maximum": 1 }, "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "pages": { "default": "first", "description": "MP4 only. \"all\" exports the whole document as one video, laying every page end to end with each page’s declared transition between them; its length comes from the document, not from durationMs.", "type": "string", "enum": [ "first", "all" ] } }, "required": [ "projectId", "format", "width", "height", "quality", "pages" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "estimate": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "quality": { "type": "number" }, "durationMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "estimatedByteSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "format", "width", "height", "quality", "estimatedByteSize" ], "additionalProperties": false } }, "required": [ "estimate" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=exports.estimate", "resource": { "kind": "design_export_estimate", "idPath": "$.estimate.estimatedByteSize" }, "effects": [ "Calculates a deterministic export-size estimate without creating an export or rendering content." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission exports:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Confirm the returned format, dimensions, duration, frame rate, and estimatedByteSize match the requested settings." ], "examples": [ { "input": { "projectId": "design_123", "format": "png", "width": 1080, "height": 1080, "quality": 0.92, "pages": "first" }, "expected": "A response matching the published outputSchema for exports.estimate." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata", "nextActionIds": [ "app_topolo_design.exports.create" ] }, "documentation": { "example_input": { "projectId": "design_123", "format": "png", "width": 1080, "height": 1080, "quality": 0.92, "pages": "first" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "POST", "path": "/api/projects/design_123/exports/estimate", "body": { "projectId": "design_123", "format": "png", "width": 1080, "height": 1080, "quality": 0.92, "pages": "first" } }, "effects": "Calculates a deterministic export-size estimate without creating an export or rendering content.", "verification": [ "Confirm the returned format, dimensions, duration, frame rate, and estimatedByteSize match the requested settings." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission exports:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=exports.estimate", "resource": { "kind": "design_export_estimate", "idPath": "$.estimate.estimatedByteSize" }, "next_action_ids": [ "app_topolo_design.exports.create" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/projects/*/exports/estimate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "exports.create", "title": "Create design export", "description": "Create a design export. SVG, PNG, and JPEG return ready. Short MP4 clips return ready too; longer clips return pending while the service encodes in the background — poll exports.get or await the export-ready notification.", "method": "POST", "path": "/api/projects/{projectId}/exports", "permission": "exports:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "width": { "type": "integer", "minimum": 320, "maximum": 4096 }, "height": { "type": "integer", "minimum": 320, "maximum": 4096 }, "quality": { "default": 0.92, "type": "number", "minimum": 0.1, "maximum": 1 }, "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "pages": { "default": "first", "description": "MP4 only. \"all\" exports the whole document as one video, laying every page end to end with each page’s declared transition between them; its length comes from the document, not from durationMs.", "type": "string", "enum": [ "first", "all" ] }, "altText": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "projectId", "format", "width", "height", "quality", "pages", "altText" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "export": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "video/mp4" ] }, "width": { "type": "integer", "minimum": 320, "maximum": 4096 }, "height": { "type": "integer", "minimum": 320, "maximum": 4096 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 500, "maximum": 30000 }, { "type": "null" } ] }, "fps": { "anyOf": [ { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, { "type": "null" } ] }, "storageKey": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "minLength": 1 }, "estimatedByteSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byteSize": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "ready" ] }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "projectId", "format", "mimeType", "width", "height", "quality", "durationMs", "fps", "storageKey", "altText", "estimatedByteSize", "byteSize", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "export" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=exports.create", "resource": { "kind": "design_export", "idPath": "$.export.id" }, "effects": [ "Creates an immutable export record. Stills and short clips come back ready; a longer MP4 comes back pending and the service encodes it in the background until exports.get reports ready." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission exports:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.exports.get with the returned export id and confirm its status and dimensions." ], "examples": [ { "input": { "projectId": "design_123", "format": "png", "width": 1080, "height": 1080, "quality": 0.92, "pages": "first", "altText": "Launch announcement" }, "expected": "A response matching the published outputSchema for exports.create." } ], "recovery": { "mode": "irreversible", "instructions": "Export records are immutable and additive; no delete or rollback action is published. Unused exports can be left unpublished safely." }, "contractSource": "design-action-metadata", "nextActionIds": [ "app_topolo_design.exports.get", "app_topolo_design.exports.upload", "app_topolo_design.exports.handoff" ] }, "documentation": { "example_input": { "projectId": "design_123", "format": "png", "width": 1080, "height": 1080, "quality": 0.92, "pages": "first", "altText": "Launch announcement" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects/design_123/exports", "body": { "projectId": "design_123", "format": "png", "width": 1080, "height": 1080, "quality": 0.92, "pages": "first", "altText": "Launch announcement" } }, "effects": "Creates an immutable export record. Stills and short clips come back ready; a longer MP4 comes back pending and the service encodes it in the background until exports.get reports ready.", "verification": [ "Call app_topolo_design.exports.get with the returned export id and confirm its status and dimensions." ], "recovery": [ { "mode": "irreversible", "instructions": "Export records are immutable and additive; no delete or rollback action is published. Unused exports can be left unpublished safely." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission exports:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=exports.create", "resource": { "kind": "design_export", "idPath": "$.export.id" }, "next_action_ids": [ "app_topolo_design.exports.get", "app_topolo_design.exports.upload", "app_topolo_design.exports.handoff" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/projects/*/exports", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "exports.upload", "title": "Upload rendered export", "description": "Upload rendered PNG, JPEG, or short MP4 bytes for an export still pending. The service renders these formats itself, so this is a fallback for content it could not produce.", "method": "PUT", "path": "/api/exports/{exportId}/content", "permission": "exports:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportId": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string", "minLength": 1, "maxLength": 34952536, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" }, "contentType": { "type": "string", "enum": [ "image/png", "image/jpeg", "video/mp4" ] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "exportId", "contentBase64", "contentType", "fileName" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "export": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "video/mp4" ] }, "width": { "type": "integer", "minimum": 320, "maximum": 4096 }, "height": { "type": "integer", "minimum": 320, "maximum": 4096 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 500, "maximum": 30000 }, { "type": "null" } ] }, "fps": { "anyOf": [ { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, { "type": "null" } ] }, "storageKey": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "minLength": 1 }, "estimatedByteSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byteSize": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "ready" ] }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "projectId", "format", "mimeType", "width", "height", "quality", "durationMs", "fps", "storageKey", "altText", "estimatedByteSize", "byteSize", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "export" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=exports.upload", "resource": { "kind": "design_export", "idPath": "$.export.id" }, "effects": [ "Stores raster or MP4 bytes for one pending export and marks the export ready." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission exports:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.exports.get and confirm the export status is ready and byteSize matches the uploaded content." ], "examples": [ { "input": { "exportId": "export_123", "contentBase64": "aGVsbG8=", "contentType": "image/png", "fileName": "launch.png" }, "expected": "A response matching the published outputSchema for exports.upload." } ], "recovery": { "mode": "irreversible", "instructions": "Uploading marks the pending export ready and cannot be undone; create a new export for corrected content." }, "contractSource": "design-action-metadata", "upload": { "profile": "inline-base64", "contentField": "contentBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 26214400, "acceptedContentTypes": [ "image/png", "image/jpeg", "video/mp4", "application/pdf", "application/vnd.openxmlformats-officedocument.presentationml.presentation" ] }, "nextActionIds": [ "app_topolo_design.exports.get", "app_topolo_design.exports.handoff" ] }, "documentation": { "example_input": { "exportId": "export_123", "contentBase64": "aGVsbG8=", "contentType": "image/png", "fileName": "launch.png" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/exports/export_123/content", "body": { "exportId": "export_123", "contentBase64": "aGVsbG8=", "contentType": "image/png", "fileName": "launch.png" } }, "effects": "Stores raster or MP4 bytes for one pending export and marks the export ready.", "verification": [ "Call app_topolo_design.exports.get and confirm the export status is ready and byteSize matches the uploaded content." ], "recovery": [ { "mode": "irreversible", "instructions": "Uploading marks the pending export ready and cannot be undone; create a new export for corrected content." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission exports:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=exports.upload", "resource": { "kind": "design_export", "idPath": "$.export.id" }, "next_action_ids": [ "app_topolo_design.exports.get", "app_topolo_design.exports.handoff" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/exports/*/content", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "exports.get", "title": "Get design export", "description": "Get export metadata and the authenticated content URL for a Design export.", "method": "GET", "path": "/api/exports/{exportId}", "permission": "exports:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportId": { "type": "string", "minLength": 1 } }, "required": [ "exportId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "export": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "video/mp4" ] }, "width": { "type": "integer", "minimum": 320, "maximum": 4096 }, "height": { "type": "integer", "minimum": 320, "maximum": 4096 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 500, "maximum": 30000 }, { "type": "null" } ] }, "fps": { "anyOf": [ { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, { "type": "null" } ] }, "storageKey": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "minLength": 1 }, "estimatedByteSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byteSize": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "ready" ] }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "projectId", "format", "mimeType", "width", "height", "quality", "durationMs", "fps", "storageKey", "altText", "estimatedByteSize", "byteSize", "status", "createdAt" ], "additionalProperties": false }, "contentUrl": { "type": "string", "minLength": 1 } }, "required": [ "export", "contentUrl" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=exports.get", "resource": { "kind": "design_export", "idPath": "$.export.id" }, "effects": [ "Reads design_export data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission exports:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected design_export context." ], "examples": [ { "input": { "exportId": "export_123" }, "expected": "A response matching the published outputSchema for exports.get." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata" }, "documentation": { "example_input": { "exportId": "export_123" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/exports/export_123", "body": null }, "effects": "Reads design_export data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected design_export context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission exports:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=exports.get", "resource": { "kind": "design_export", "idPath": "$.export.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/exports/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "exports.handoff", "title": "Create social handoff", "description": "Create a media descriptor for Social Studio or Socialize from a ready export.", "method": "POST", "path": "/api/exports/{exportId}/handoffs", "permission": "exports:handoff", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportId": { "type": "string", "minLength": 1 }, "target": { "type": "string", "enum": [ "social_studio", "socialize" ] }, "externalResourceId": { "type": "string", "minLength": 1 } }, "required": [ "exportId", "target" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "handoff": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "social_studio", "socialize" ] }, "externalResourceId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "projectId": { "type": "string", "minLength": 1 }, "exportId": { "type": "string", "minLength": 1 }, "mediaUrl": { "type": "string", "minLength": 1 }, "requiresCredential": { "type": "boolean" }, "filename": { "type": "string", "minLength": 1 }, "mediaType": { "type": "string", "enum": [ "image", "video" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "video/mp4" ] }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "fps": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "byteSize": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "altText": { "type": "string", "minLength": 1 } }, "required": [ "target", "externalResourceId", "projectId", "exportId", "mediaUrl", "requiresCredential", "filename", "mediaType", "mimeType", "width", "height", "durationMs", "fps", "byteSize", "altText" ], "additionalProperties": false } }, "required": [ "handoff" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=exports.handoff", "resource": { "kind": "design_export", "idPath": "$.handoff.exportId" }, "effects": [ "Returns a provenance-preserving media descriptor for a ready export without mutating the target application." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission exports:handoff and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Confirm the descriptor exportId, projectId, MIME type, dimensions, and authenticated content URL match app_topolo_design.exports.get." ], "examples": [ { "input": { "exportId": "export_123", "target": "socialize" }, "expected": "A response matching the published outputSchema for exports.handoff." } ], "recovery": { "mode": "not_applicable", "instructions": "Produces a provenance-preserving media descriptor without mutating Design or the target application; discard the descriptor if unused." }, "contractSource": "design-action-metadata", "nextActionIds": [ "app_topolo_social_studio.assets.upload", "app_topolo_socialize.media.upload_url.create", "app_topolo_socialize.media.upload.complete" ] }, "documentation": { "example_input": { "exportId": "export_123", "target": "socialize" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/exports/export_123/handoffs", "body": { "exportId": "export_123", "target": "socialize" } }, "effects": "Returns a provenance-preserving media descriptor for a ready export without mutating the target application.", "verification": [ "Confirm the descriptor exportId, projectId, MIME type, dimensions, and authenticated content URL match app_topolo_design.exports.get." ], "recovery": [ { "mode": "not_applicable", "instructions": "Produces a provenance-preserving media descriptor without mutating Design or the target application; discard the descriptor if unused." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission exports:handoff and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=exports.handoff", "resource": { "kind": "design_export", "idPath": "$.handoff.exportId" }, "next_action_ids": [ "app_topolo_social_studio.assets.upload", "app_topolo_socialize.media.upload_url.create", "app_topolo_socialize.media.upload.complete" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/exports/*/handoffs", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.list", "title": "List uploaded media", "description": "List reusable source images and videos uploaded to the selected Design workspace.", "method": "GET", "path": "/api/media", "permission": "media:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string", "minLength": 1 }, "limit": { "default": 48, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "limit" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "const": "upload" }, "name": { "type": "string", "minLength": 1 }, "fileName": { "type": "string", "minLength": 1 }, "projectId": { "type": "null" }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "webp", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp", "video/mp4" ] }, "mediaType": { "type": "string", "enum": [ "image", "video" ] }, "width": { "type": "null" }, "height": { "type": "null" }, "durationMs": { "type": "null" }, "altText": { "type": "string", "minLength": 1 }, "byteSize": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "const": "ready" }, "createdAt": { "type": "string", "minLength": 1 }, "contentUrl": { "type": "string", "minLength": 1 } }, "required": [ "id", "source", "name", "fileName", "projectId", "format", "mimeType", "mediaType", "width", "height", "durationMs", "altText", "byteSize", "status", "createdAt", "contentUrl" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "media", "nextCursor" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=media.list", "resource": { "kind": "design_media", "idPath": "$.media[].id" }, "effects": [ "Lists reusable source media uploaded to the selected Design workspace. Generated exports are intentionally excluded." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission media:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Confirm each returned item is an uploaded source asset in the selected workspace." ], "examples": [ { "input": { "limit": 48 }, "expected": "A response matching the published outputSchema for media.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata", "nextActionIds": [ "app_topolo_design.media.upload", "app_topolo_design.media.delete" ] }, "documentation": { "example_input": { "limit": 48 }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/media", "body": null }, "effects": "Lists reusable source media uploaded to the selected Design workspace. Generated exports are intentionally excluded.", "verification": [ "Confirm each returned item is an uploaded source asset in the selected workspace." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission media:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=media.list", "resource": { "kind": "design_media", "idPath": "$.media[].id" }, "next_action_ids": [ "app_topolo_design.media.upload", "app_topolo_design.media.delete" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/media", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.upload", "title": "Upload source media", "description": "Upload a reusable source image or video to the selected Design workspace Media library.", "method": "POST", "path": "/api/media", "permission": "media:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentBase64": { "type": "string", "minLength": 1, "maxLength": 34952536, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" }, "contentType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp", "video/mp4" ] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "altText": { "type": "string", "maxLength": 500 } }, "required": [ "contentBase64", "contentType", "fileName" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "media": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "const": "upload" }, "name": { "type": "string", "minLength": 1 }, "fileName": { "type": "string", "minLength": 1 }, "projectId": { "type": "null" }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "webp", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp", "video/mp4" ] }, "mediaType": { "type": "string", "enum": [ "image", "video" ] }, "width": { "type": "null" }, "height": { "type": "null" }, "durationMs": { "type": "null" }, "altText": { "type": "string", "minLength": 1 }, "byteSize": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "const": "ready" }, "createdAt": { "type": "string", "minLength": 1 }, "contentUrl": { "type": "string", "minLength": 1 } }, "required": [ "id", "source", "name", "fileName", "projectId", "format", "mimeType", "mediaType", "width", "height", "durationMs", "altText", "byteSize", "status", "createdAt", "contentUrl" ], "additionalProperties": false } }, "required": [ "media" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=media.upload", "resource": { "kind": "design_media", "idPath": "$.media.id" }, "effects": [ "Stores one reusable source asset in the selected workspace media library." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission media:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.media.list and confirm the returned id, filename, MIME type, and byte size." ], "examples": [ { "input": { "contentBase64": "aGVsbG8=", "contentType": "image/png", "fileName": "launch.png", "altText": "Launch artwork" }, "expected": "A response matching the published outputSchema for media.upload." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_design.media.delete", "instructions": "Call media.delete with the returned media id if the source asset is not referenced by any design." }, "contractSource": "design-action-metadata", "upload": { "profile": "inline-base64", "contentField": "contentBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 26214400, "acceptedContentTypes": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp", "video/mp4" ] }, "nextActionIds": [ "app_topolo_design.media.list", "app_topolo_design.media.delete" ] }, "documentation": { "example_input": { "contentBase64": "aGVsbG8=", "contentType": "image/png", "fileName": "launch.png", "altText": "Launch artwork" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/media", "body": { "contentBase64": "aGVsbG8=", "contentType": "image/png", "fileName": "launch.png", "altText": "Launch artwork" } }, "effects": "Stores one reusable source asset in the selected workspace media library.", "verification": [ "Call app_topolo_design.media.list and confirm the returned id, filename, MIME type, and byte size." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_design.media.delete", "instructions": "Call media.delete with the returned media id if the source asset is not referenced by any design." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission media:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=media.upload", "resource": { "kind": "design_media", "idPath": "$.media.id" }, "next_action_ids": [ "app_topolo_design.media.list", "app_topolo_design.media.delete" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/media", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.generate", "title": "Generate source media", "description": "Generate an image through the governed provider gateway and store it in the selected Design workspace.", "method": "POST", "path": "/api/media/generate", "permission": "media:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "prompt": { "type": "string", "minLength": 10, "maxLength": 1000 }, "aspectRatio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4" ] }, "provider": { "type": "string", "enum": [ "openai", "google", "xai", "cloudflare" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "sourceAsset": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "mimeType": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "url" ], "additionalProperties": false }, "fileName": { "type": "string", "minLength": 1, "maxLength": 120 }, "altText": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "prompt" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "media": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "const": "upload" }, "name": { "type": "string", "minLength": 1 }, "fileName": { "type": "string", "minLength": 1 }, "projectId": { "type": "null" }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "webp", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp", "video/mp4" ] }, "mediaType": { "type": "string", "enum": [ "image", "video" ] }, "width": { "type": "null" }, "height": { "type": "null" }, "durationMs": { "type": "null" }, "altText": { "type": "string", "minLength": 1 }, "byteSize": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "const": "ready" }, "createdAt": { "type": "string", "minLength": 1 }, "contentUrl": { "type": "string", "minLength": 1 } }, "required": [ "id", "source", "name", "fileName", "projectId", "format", "mimeType", "mediaType", "width", "height", "durationMs", "altText", "byteSize", "status", "createdAt", "contentUrl" ], "additionalProperties": false }, "generation": { "type": "object", "properties": { "provider": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "provider", "model" ], "additionalProperties": false } }, "required": [ "media", "generation" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=media.generate", "resource": { "kind": "design_media", "idPath": "$.media.id" }, "effects": [ "Generates one image through the governed provider gateway and stores it as reusable workspace media." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission media:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.media.list and confirm the generated media id, MIME type, and content URL." ], "examples": [ { "input": { "prompt": "A bold editorial illustration of software removing repetitive work", "aspectRatio": "4:3" }, "expected": "A response matching the published outputSchema for media.generate." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_design.media.delete", "instructions": "Call media.delete with the returned media id while it remains unreferenced." }, "contractSource": "design-action-metadata", "nextActionIds": [ "app_topolo_design.media.list", "app_topolo_design.projects.update", "app_topolo_design.media.delete_availability" ] }, "documentation": { "example_input": { "prompt": "A bold editorial illustration of software removing repetitive work", "aspectRatio": "4:3" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/media/generate", "body": { "prompt": "A bold editorial illustration of software removing repetitive work", "aspectRatio": "4:3" } }, "effects": "Generates one image through the governed provider gateway and stores it as reusable workspace media.", "verification": [ "Call app_topolo_design.media.list and confirm the generated media id, MIME type, and content URL." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_design.media.delete", "instructions": "Call media.delete with the returned media id while it remains unreferenced." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission media:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=media.generate", "resource": { "kind": "design_media", "idPath": "$.media.id" }, "next_action_ids": [ "app_topolo_design.media.list", "app_topolo_design.projects.update", "app_topolo_design.media.delete_availability" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/media/generate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.delete_availability", "title": "Check media deletion", "description": "Check whether a source asset is unreferenced and safe to delete.", "method": "GET", "path": "/api/media/{mediaId}/deletion", "permission": "media:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mediaId": { "type": "string", "minLength": 1 } }, "required": [ "mediaId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "allowed" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=media.delete_availability", "resource": { "kind": "design_media", "idPath": "$.allowed" }, "effects": [ "Checks whether workspace media is unreferenced and therefore safe to delete without changing it." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission media:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Treat allowed false and its reason as authoritative; do not call media.delete until allowed is true." ], "examples": [ { "input": { "mediaId": "design_media_123" }, "expected": "A response matching the published outputSchema for media.delete_availability." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata", "nextActionIds": [ "app_topolo_design.media.delete" ] }, "documentation": { "example_input": { "mediaId": "design_media_123" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/media/design_media_123/deletion", "body": null }, "effects": "Checks whether workspace media is unreferenced and therefore safe to delete without changing it.", "verification": [ "Treat allowed false and its reason as authoritative; do not call media.delete until allowed is true." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission media:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=media.delete_availability", "resource": { "kind": "design_media", "idPath": "$.allowed" }, "next_action_ids": [ "app_topolo_design.media.delete" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/media/*/deletion", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "media.delete", "title": "Delete source media", "description": "Permanently delete an unreferenced source asset from the selected Design workspace Media library.", "method": "DELETE", "path": "/api/media/{mediaId}", "permission": "media:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mediaId": { "type": "string", "minLength": 1 } }, "required": [ "mediaId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "mediaId": { "type": "string", "minLength": 1 } }, "required": [ "deleted", "mediaId" ], "additionalProperties": false }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=media.delete", "resource": { "kind": "design_media", "idPath": "$.mediaId" }, "effects": [ "Permanently removes one unreferenced source asset from the selected workspace media library." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission media:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.media.list and confirm the deleted media id is absent." ], "examples": [ { "input": { "mediaId": "design_media_123" }, "expected": "A response matching the published outputSchema for media.delete." } ], "recovery": { "mode": "irreversible", "instructions": "Deletion is permanent. Upload the source file again if it is needed later." }, "contractSource": "design-action-metadata" }, "documentation": { "example_input": { "mediaId": "design_media_123" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/media/design_media_123", "body": null }, "effects": "Permanently removes one unreferenced source asset from the selected workspace media library.", "verification": [ "Call app_topolo_design.media.list and confirm the deleted media id is absent." ], "recovery": [ { "mode": "irreversible", "instructions": "Deletion is permanent. Upload the source file again if it is needed later." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission media:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=media.delete", "resource": { "kind": "design_media", "idPath": "$.mediaId" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/media/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "fonts.list", "title": "List workspace fonts", "description": "List uploaded workspace fonts and their authenticated content URLs.", "method": "GET", "path": "/api/fonts", "permission": "fonts:read", "readOnly": true, "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": { "fonts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "family": { "type": "string", "minLength": 1 }, "source": { "type": "string", "const": "workspace" }, "contentType": { "type": "string", "enum": [ "font/woff2", "font/woff", "application/font-woff", "font/ttf", "application/x-font-ttf", "font/otf", "application/x-font-opentype" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] }, "contentUrl": { "type": "string", "minLength": 1 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" } }, "required": [ "id", "family", "source", "contentType", "format", "contentUrl" ], "additionalProperties": false } } }, "required": [ "fonts" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=fonts.list", "resource": { "kind": "design_font", "idPath": "$.fonts[].id" }, "effects": [ "Lists workspace font assets with authenticated content URLs for use in Design documents." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission fonts:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Confirm each font belongs to the selected workspace and has a supported content type and format." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for fonts.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata", "nextActionIds": [ "app_topolo_design.fonts.upload", "app_topolo_design.projects.update" ] }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/fonts", "body": null }, "effects": "Lists workspace font assets with authenticated content URLs for use in Design documents.", "verification": [ "Confirm each font belongs to the selected workspace and has a supported content type and format." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission fonts:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=fonts.list", "resource": { "kind": "design_font", "idPath": "$.fonts[].id" }, "next_action_ids": [ "app_topolo_design.fonts.upload", "app_topolo_design.projects.update" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/fonts", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "fonts.upload", "title": "Upload workspace font", "description": "Upload one licensed font file for use in Design documents.", "method": "POST", "path": "/api/fonts", "permission": "fonts:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 120 }, "fileName": { "type": "string", "minLength": 1, "maxLength": 240 }, "contentType": { "type": "string", "enum": [ "font/woff2", "font/woff", "application/font-woff", "font/ttf", "application/x-font-ttf", "font/otf", "application/x-font-opentype" ] }, "contentBase64": { "type": "string", "minLength": 1, "maxLength": 2796204, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" }, "license": { "type": "string", "minLength": 1, "maxLength": 240 } }, "required": [ "family", "fileName", "contentType", "contentBase64", "license" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "font": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "family": { "type": "string", "minLength": 1 }, "source": { "type": "string", "const": "workspace" }, "contentType": { "type": "string", "enum": [ "font/woff2", "font/woff", "application/font-woff", "font/ttf", "application/x-font-ttf", "font/otf", "application/x-font-opentype" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] }, "contentUrl": { "type": "string", "minLength": 1 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" } }, "required": [ "id", "family", "source", "contentType", "format", "sourceUrl" ], "additionalProperties": false } }, "required": [ "font" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=fonts.upload", "resource": { "kind": "design_font", "idPath": "$.font.id" }, "effects": [ "Stores one licensed font file in the selected Design workspace and returns a document-ready embedded source URL." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission fonts:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.fonts.list and confirm the returned font id, family, content type, and format." ], "examples": [ { "input": { "family": "Acme Sans", "fileName": "acme.woff2", "contentType": "font/woff2", "contentBase64": "Zm9udA==", "license": "Company licence" }, "expected": "A response matching the published outputSchema for fonts.upload." } ], "recovery": { "mode": "irreversible", "instructions": "No font deletion contract exists because projects can embed the returned source. Upload only licensed files intended for this workspace." }, "contractSource": "design-action-metadata", "upload": { "profile": "inline-base64", "contentField": "contentBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 2097152, "acceptedContentTypes": [ "font/woff2", "font/woff", "application/font-woff", "font/ttf", "application/x-font-ttf", "font/otf", "application/x-font-opentype" ] }, "nextActionIds": [ "app_topolo_design.fonts.list", "app_topolo_design.projects.update" ] }, "documentation": { "example_input": { "family": "Acme Sans", "fileName": "acme.woff2", "contentType": "font/woff2", "contentBase64": "Zm9udA==", "license": "Company licence" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/fonts", "body": { "family": "Acme Sans", "fileName": "acme.woff2", "contentType": "font/woff2", "contentBase64": "Zm9udA==", "license": "Company licence" } }, "effects": "Stores one licensed font file in the selected Design workspace and returns a document-ready embedded source URL.", "verification": [ "Call app_topolo_design.fonts.list and confirm the returned font id, family, content type, and format." ], "recovery": [ { "mode": "irreversible", "instructions": "No font deletion contract exists because projects can embed the returned source. Upload only licensed files intended for this workspace." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission fonts:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=fonts.upload", "resource": { "kind": "design_font", "idPath": "$.font.id" }, "next_action_ids": [ "app_topolo_design.fonts.list", "app_topolo_design.projects.update" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/fonts", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "stock.list", "title": "List stock images", "description": "List the shared searchable Design stock image collection.", "method": "GET", "path": "/api/stock", "permission": "workspace:read", "readOnly": true, "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": { "stock": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "orientation": { "type": "string", "enum": [ "portrait", "landscape", "square" ] }, "altText": { "type": "string", "minLength": 1 }, "contentUrl": { "type": "string", "minLength": 1 } }, "required": [ "name", "title", "tags", "orientation", "altText", "contentUrl" ], "additionalProperties": false } } }, "required": [ "stock" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=stock.list", "resource": { "kind": "design_stock", "idPath": "$.stock[].name" }, "effects": [ "Lists the shared Design stock collection with searchable metadata and public immutable content paths." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission workspace:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Confirm each returned stock name is a safe collection entry before using /api/stock/{name}." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for stock.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata", "nextActionIds": [ "app_topolo_design.projects.update" ] }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/stock", "body": null }, "effects": "Lists the shared Design stock collection with searchable metadata and public immutable content paths.", "verification": [ "Confirm each returned stock name is a safe collection entry before using /api/stock/{name}." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission workspace:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=stock.list", "resource": { "kind": "design_stock", "idPath": "$.stock[].name" }, "next_action_ids": [ "app_topolo_design.projects.update" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/stock", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "stock.upload", "title": "Upload stock image", "description": "Add an approved image to the immutable stock collection shared by every Design workspace.", "method": "POST", "path": "/api/stock", "permission": "library:publish", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentBase64": { "type": "string", "minLength": 1, "maxLength": 13981016, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" }, "contentType": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp" ] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 240 }, "altText": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "contentBase64", "contentType", "fileName" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "stock": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "orientation": { "type": "string", "enum": [ "portrait", "landscape", "square" ] }, "altText": { "type": "string", "minLength": 1 }, "contentUrl": { "type": "string", "minLength": 1 } }, "required": [ "name", "title", "tags", "orientation", "altText", "contentUrl" ], "additionalProperties": false }, "byteSize": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "stock", "byteSize" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=stock.upload", "resource": { "kind": "design_stock", "idPath": "$.stock.name" }, "effects": [ "Adds one content-addressed image to the immutable stock collection shared by every Design workspace." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission library:publish and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.stock.list and confirm the returned content-addressed stock name and metadata are present." ], "examples": [ { "input": { "contentBase64": "aGVsbG8=", "contentType": "image/png", "fileName": "shared-table.png", "altText": "A shared table of dishes." }, "expected": "A response matching the published outputSchema for stock.upload." } ], "recovery": { "mode": "irreversible", "instructions": "No stock-retirement action exists. Upload only images approved for the shared Design stock collection." }, "contractSource": "design-action-metadata", "upload": { "profile": "inline-base64", "contentField": "contentBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 10485760, "acceptedContentTypes": [ "image/png", "image/jpeg", "image/webp" ] }, "nextActionIds": [ "app_topolo_design.stock.list", "app_topolo_design.projects.update" ] }, "documentation": { "example_input": { "contentBase64": "aGVsbG8=", "contentType": "image/png", "fileName": "shared-table.png", "altText": "A shared table of dishes." }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/stock", "body": { "contentBase64": "aGVsbG8=", "contentType": "image/png", "fileName": "shared-table.png", "altText": "A shared table of dishes." } }, "effects": "Adds one content-addressed image to the immutable stock collection shared by every Design workspace.", "verification": [ "Call app_topolo_design.stock.list and confirm the returned content-addressed stock name and metadata are present." ], "recovery": [ { "mode": "irreversible", "instructions": "No stock-retirement action exists. Upload only images approved for the shared Design stock collection." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission library:publish and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=stock.upload", "resource": { "kind": "design_stock", "idPath": "$.stock.name" }, "next_action_ids": [ "app_topolo_design.stock.list", "app_topolo_design.projects.update" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/stock", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "settings.get", "title": "Get Design settings", "description": "Get workspace canvas, Brand, export, and motion defaults for Design.", "method": "GET", "path": "/api/settings", "permission": "settings:read", "readOnly": true, "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": { "settings": { "type": "object", "properties": { "defaultBrandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "defaultCanvasWidth": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultCanvasHeight": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultExportFormat": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "defaultExportScale": { "type": "number" }, "defaultExportQuality": { "type": "number" }, "defaultExportTransparent": { "type": "boolean" }, "defaultAnimationDurationMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultAnimationFps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] } }, "required": [ "defaultBrandKitId", "defaultCanvasWidth", "defaultCanvasHeight", "defaultExportFormat", "defaultExportScale", "defaultExportQuality", "defaultExportTransparent", "defaultAnimationDurationMs", "defaultAnimationFps" ], "additionalProperties": false } }, "required": [ "settings" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=settings.get", "resource": { "kind": "workspace", "idPath": "$.settings.defaultCanvasWidth" }, "effects": [ "Reads workspace data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission settings:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected workspace context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for settings.get." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/settings", "body": null }, "effects": "Reads workspace data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected workspace context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission settings:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=settings.get", "resource": { "kind": "workspace", "idPath": "$.settings.defaultCanvasWidth" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "settings.update", "title": "Update Design settings", "description": "Update workspace canvas, Brand, export, or motion defaults for Design.", "method": "PATCH", "path": "/api/settings", "permission": "settings:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "defaultBrandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "defaultCanvasWidth": { "type": "integer", "minimum": 64, "maximum": 8192 }, "defaultCanvasHeight": { "type": "integer", "minimum": 64, "maximum": 8192 }, "defaultExportFormat": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "defaultExportScale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "defaultExportQuality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "defaultExportTransparent": { "type": "boolean" }, "defaultAnimationDurationMs": { "type": "integer", "minimum": 1500, "maximum": 30000 }, "defaultAnimationFps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] } }, "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "settings": { "type": "object", "properties": { "defaultBrandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "defaultCanvasWidth": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultCanvasHeight": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultExportFormat": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "defaultExportScale": { "type": "number" }, "defaultExportQuality": { "type": "number" }, "defaultExportTransparent": { "type": "boolean" }, "defaultAnimationDurationMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultAnimationFps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] } }, "required": [ "defaultBrandKitId", "defaultCanvasWidth", "defaultCanvasHeight", "defaultExportFormat", "defaultExportScale", "defaultExportQuality", "defaultExportTransparent", "defaultAnimationDurationMs", "defaultAnimationFps" ], "additionalProperties": false } }, "required": [ "settings" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=settings.update", "resource": { "kind": "workspace", "idPath": "$.settings.defaultCanvasWidth" }, "effects": [ "Updates workspace defaults used when new Design projects are created." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission settings:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.settings.get and confirm the persisted defaults match the request." ], "examples": [ { "input": { "defaultBrandKitId": "brand_123", "defaultCanvasWidth": 1080, "defaultCanvasHeight": 1350, "defaultExportFormat": "png" }, "expected": "A response matching the published outputSchema for settings.update." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_design.settings.update", "requiresSnapshot": true, "instructions": "Capture settings.get before updating, then call settings.update with the prior values to restore them." }, "contractSource": "design-action-metadata" }, "documentation": { "example_input": { "defaultBrandKitId": "brand_123", "defaultCanvasWidth": 1080, "defaultCanvasHeight": 1350, "defaultExportFormat": "png" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/settings", "body": { "defaultBrandKitId": "brand_123", "defaultCanvasWidth": 1080, "defaultCanvasHeight": 1350, "defaultExportFormat": "png" } }, "effects": "Updates workspace defaults used when new Design projects are created.", "verification": [ "Call app_topolo_design.settings.get and confirm the persisted defaults match the request." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_design.settings.update", "requiresSnapshot": true, "instructions": "Capture settings.get before updating, then call settings.update with the prior values to restore them." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission settings:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=settings.update", "resource": { "kind": "workspace", "idPath": "$.settings.defaultCanvasWidth" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.export", "title": "Export workspace data", "description": "Export Design projects, uploaded media metadata, generated export metadata, and settings for the selected workspace.", "method": "GET", "path": "/api/privacy/export", "permission": "privacy:read", "readOnly": true, "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": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "document", "createdAt", "updatedAt" ], "additionalProperties": false } }, "exports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "video/mp4" ] }, "width": { "type": "integer", "minimum": 320, "maximum": 4096 }, "height": { "type": "integer", "minimum": 320, "maximum": 4096 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 500, "maximum": 30000 }, { "type": "null" } ] }, "fps": { "anyOf": [ { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, { "type": "null" } ] }, "storageKey": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "minLength": 1 }, "estimatedByteSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byteSize": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "ready" ] }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "projectId", "format", "mimeType", "width", "height", "quality", "durationMs", "fps", "storageKey", "altText", "estimatedByteSize", "byteSize", "status", "createdAt" ], "additionalProperties": false } }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "fileName": { "type": "string", "minLength": 1 }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp", "video/mp4" ] }, "mediaType": { "type": "string", "enum": [ "image", "video" ] }, "storageKey": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "minLength": 1 }, "byteSize": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "fileName", "mimeType", "mediaType", "storageKey", "altText", "byteSize", "createdAt" ], "additionalProperties": false } }, "settings": { "type": "object", "properties": { "defaultBrandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "defaultCanvasWidth": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultCanvasHeight": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultExportFormat": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "defaultExportScale": { "type": "number" }, "defaultExportQuality": { "type": "number" }, "defaultExportTransparent": { "type": "boolean" }, "defaultAnimationDurationMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultAnimationFps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] } }, "required": [ "defaultBrandKitId", "defaultCanvasWidth", "defaultCanvasHeight", "defaultExportFormat", "defaultExportScale", "defaultExportQuality", "defaultExportTransparent", "defaultAnimationDurationMs", "defaultAnimationFps" ], "additionalProperties": false } }, "required": [ "projects", "exports", "media", "settings" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=privacy.export", "resource": { "kind": "workspace", "idPath": "$.workspaceId" }, "effects": [ "Reads workspace data without changing service state." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission privacy:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Validate the response against outputSchema and confirm it belongs to the selected workspace context." ], "examples": [ { "input": {}, "expected": "A response matching the published outputSchema for privacy.export." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata" }, "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/privacy/export", "body": null }, "effects": "Reads workspace data without changing service state.", "verification": [ "Validate the response against outputSchema and confirm it belongs to the selected workspace context." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission privacy:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=privacy.export", "resource": { "kind": "workspace", "idPath": "$.workspaceId" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/privacy/export", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "library.list", "title": "List starter library templates", "description": "List one page of the starter templates published to every workspace. Returns card metadata without documents; needs no workspace of its own.", "method": "GET", "path": "/api/templates", "permission": "library:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string", "minLength": 1, "maxLength": 200 }, "limit": { "type": "integer", "minimum": 1, "maximum": 60 }, "category": { "type": "string", "enum": [ "Social", "Presentations", "Documents", "Marketing", "Print" ] }, "style": { "type": "string", "enum": [ "Bold", "Minimal", "Editorial", "Playful", "Professional" ] }, "q": { "type": "string", "minLength": 1, "maxLength": 120 } }, "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "style": { "type": "string" }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pageCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "category", "style", "width", "height", "pageCount", "updatedAt" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "templates", "total", "nextCursor" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=library.list", "resource": { "kind": "design_library_template", "idPath": "$.templates[].id" }, "effects": [ "Reads one page of the starter library, which is shared by every workspace and needs none.", "Returns card metadata without documents; pass the returned nextCursor to read the following page." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission library:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Confirm the returned page count matches the requested limit and that nextCursor is null on the last page." ], "examples": [ { "input": { "limit": 12, "category": "Social" }, "expected": "A response matching the published outputSchema for library.list." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata", "nextActionIds": [ "app_topolo_design.library.get", "app_topolo_design.projects.create" ] }, "documentation": { "example_input": { "limit": 12, "category": "Social" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/templates", "body": null }, "effects": "Reads one page of the starter library, which is shared by every workspace and needs none. Returns card metadata without documents; pass the returned nextCursor to read the following page.", "verification": [ "Confirm the returned page count matches the requested limit and that nextCursor is null on the last page." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission library:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=library.list", "resource": { "kind": "design_library_template", "idPath": "$.templates[].id" }, "next_action_ids": [ "app_topolo_design.library.get", "app_topolo_design.projects.create" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/templates", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "library.get", "title": "Read one starter library template", "description": "Read one starter-library template including its full design document. Needs no workspace of its own.", "method": "GET", "path": "/api/templates/{id}", "permission": "library:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "id" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "template": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "style": { "type": "string" }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pageCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updatedAt": { "type": "string" }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." } }, "required": [ "id", "name", "description", "category", "style", "width", "height", "pageCount", "updatedAt", "document" ], "additionalProperties": false } }, "required": [ "template" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=library.get", "resource": { "kind": "design_library_template", "idPath": "$.template.id" }, "effects": [ "Reads one starter-library template including its full design document." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission library:read and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Confirm the returned document carries at least one page and the id matches the request." ], "examples": [ { "input": { "id": "after-hours-launch" }, "expected": "A response matching the published outputSchema for library.get." } ], "recovery": { "mode": "not_applicable", "instructions": "This action does not change service state." }, "contractSource": "design-action-metadata", "nextActionIds": [ "app_topolo_design.projects.create" ] }, "documentation": { "example_input": { "id": "after-hours-launch" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/templates/after-hours-launch", "body": null }, "effects": "Reads one starter-library template including its full design document.", "verification": [ "Confirm the returned document carries at least one page and the id matches the request." ], "recovery": [ { "mode": "not_applicable", "instructions": "This action does not change service state." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission library:read and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=library.get", "resource": { "kind": "design_library_template", "idPath": "$.template.id" }, "next_action_ids": [ "app_topolo_design.projects.create" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/templates/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "library.publish", "title": "Publish a library template", "description": "Publish a design into the starter library shared by every workspace, or replace the one already published under this id. Only the organization that owns Design may call this.", "method": "POST", "path": "/api/templates", "permission": "library:publish", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "summary": { "default": "", "type": "string", "maxLength": 280 }, "category": { "default": "Documents", "type": "string", "enum": [ "Social", "Presentations", "Documents", "Marketing", "Print" ] }, "style": { "default": "Minimal", "type": "string", "enum": [ "Bold", "Minimal", "Editorial", "Playful", "Professional" ] }, "rank": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9999 }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." } }, "required": [ "id", "name", "summary", "category", "style", "rank", "document" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "template": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "style": { "type": "string" }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pageCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updatedAt": { "type": "string" }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." } }, "required": [ "id", "name", "description", "category", "style", "width", "height", "pageCount", "updatedAt", "document" ], "additionalProperties": false } }, "required": [ "template" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=library.publish", "resource": { "kind": "design_library_template", "idPath": "$.template.id" }, "effects": [ "Publishes one design into the starter library shared by every workspace, or replaces the one already published under this id.", "Refused unless the calling organization owns the Design application." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission library:publish and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.library.list and confirm the template appears with the expected name and page count." ], "examples": [ { "input": { "id": "starter-launch-post", "name": "Launch post", "summary": "A single-card launch announcement.", "category": "Social", "style": "Bold", "rank": 0, "document": { "schemaVersion": 5, "brand": null, "fontSources": [], "pages": [ { "id": "page_1", "name": "Cover", "canvas": { "width": 1080, "height": 1350, "background": "#0A2440" }, "elements": [ { "id": "title", "name": "Display title", "purpose": "Headline", "type": "text", "frame": { "x": 92, "y": 400, "width": 896, "height": 240, "rotation": 0 }, "opacity": 1, "hidden": false, "locked": false, "text": "A starter design", "style": { "fontFamily": "Helvetica Neue, Helvetica, Arial, sans-serif", "fontSize": 96, "minFontSize": 48, "maxFontSize": 96, "autoFit": true, "fontWeight": 800, "lineHeight": 1.05, "letterSpacing": -2, "color": "#FFFFFF", "textAlign": "left", "verticalAlign": "middle" } } ], "animation": { "durationMs": 3000, "fps": 24, "motions": [] } } ], "exportSettings": { "format": "png", "scale": 2, "quality": 0.92, "transparent": false } } }, "expected": "A response matching the published outputSchema for library.publish." } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_design.library.retire", "instructions": "Invoke app_topolo_design.library.retire with the same id to take the template back out of the library." }, "contractSource": "design-action-metadata", "rollbackActionId": "app_topolo_design.library.retire", "nextActionIds": [ "app_topolo_design.library.list" ] }, "documentation": { "example_input": { "id": "starter-launch-post", "name": "Launch post", "summary": "A single-card launch announcement.", "category": "Social", "style": "Bold", "rank": 0, "document": { "schemaVersion": 5, "brand": null, "fontSources": [], "pages": [ { "id": "page_1", "name": "Cover", "canvas": { "width": 1080, "height": 1350, "background": "#0A2440" }, "elements": [ { "id": "title", "name": "Display title", "purpose": "Headline", "type": "text", "frame": { "x": 92, "y": 400, "width": 896, "height": 240, "rotation": 0 }, "opacity": 1, "hidden": false, "locked": false, "text": "A starter design", "style": { "fontFamily": "Helvetica Neue, Helvetica, Arial, sans-serif", "fontSize": 96, "minFontSize": 48, "maxFontSize": 96, "autoFit": true, "fontWeight": 800, "lineHeight": 1.05, "letterSpacing": -2, "color": "#FFFFFF", "textAlign": "left", "verticalAlign": "middle" } } ], "animation": { "durationMs": 3000, "fps": 24, "motions": [] } } ], "exportSettings": { "format": "png", "scale": 2, "quality": 0.92, "transparent": false } } }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/templates", "body": { "id": "starter-launch-post", "name": "Launch post", "summary": "A single-card launch announcement.", "category": "Social", "style": "Bold", "rank": 0, "document": { "schemaVersion": 5, "brand": null, "fontSources": [], "pages": [ { "id": "page_1", "name": "Cover", "canvas": { "width": 1080, "height": 1350, "background": "#0A2440" }, "elements": [ { "id": "title", "name": "Display title", "purpose": "Headline", "type": "text", "frame": { "x": 92, "y": 400, "width": 896, "height": 240, "rotation": 0 }, "opacity": 1, "hidden": false, "locked": false, "text": "A starter design", "style": { "fontFamily": "Helvetica Neue, Helvetica, Arial, sans-serif", "fontSize": 96, "minFontSize": 48, "maxFontSize": 96, "autoFit": true, "fontWeight": 800, "lineHeight": 1.05, "letterSpacing": -2, "color": "#FFFFFF", "textAlign": "left", "verticalAlign": "middle" } } ], "animation": { "durationMs": 3000, "fps": 24, "motions": [] } } ], "exportSettings": { "format": "png", "scale": 2, "quality": 0.92, "transparent": false } } } }, "effects": "Publishes one design into the starter library shared by every workspace, or replaces the one already published under this id. Refused unless the calling organization owns the Design application.", "verification": [ "Call app_topolo_design.library.list and confirm the template appears with the expected name and page count." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_design.library.retire", "instructions": "Invoke app_topolo_design.library.retire with the same id to take the template back out of the library." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission library:publish and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=library.publish", "resource": { "kind": "design_library_template", "idPath": "$.template.id" }, "next_action_ids": [ "app_topolo_design.library.list" ], "rollback_action_id": "app_topolo_design.library.retire" }, "implementation": { "status": "implemented", "route_key": "POST /api/templates", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "library.retire", "title": "Retire a library template", "description": "Remove a template from the starter library without deleting the project behind it. Only the organization that owns Design may call this.", "method": "DELETE", "path": "/api/templates/:id", "permission": "library:publish", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "id" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "retired": { "type": "string" } }, "required": [ "retired" ], "additionalProperties": false }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=library.retire", "resource": { "kind": "design_library_template", "idPath": "$.retired" }, "effects": [ "Removes one template from the starter library without deleting the project behind it.", "Refused unless the calling organization owns the Design application." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission library:publish and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.library.list and confirm the template is no longer listed." ], "examples": [ { "input": { "id": "starter-launch-post" }, "expected": "A response matching the published outputSchema for library.retire." } ], "recovery": { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "contractSource": "design-action-metadata", "nextActionIds": [ "app_topolo_design.library.list" ] }, "documentation": { "example_input": { "id": "starter-launch-post" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/templates/:id", "body": null }, "effects": "Removes one template from the starter library without deleting the project behind it. Refused unless the calling organization owns the Design application.", "verification": [ "Call app_topolo_design.library.list and confirm the template is no longer listed." ], "recovery": [ { "mode": "irreversible", "instructions": "No safe automatic inverse is published. Confirm the change and retain any required export or snapshot before calling." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission library:publish and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=library.retire", "resource": { "kind": "design_library_template", "idPath": "$.retired" }, "next_action_ids": [ "app_topolo_design.library.list" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/templates/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.erase", "title": "Erase workspace data", "description": "Permanently erase Design projects, uploaded media, generated exports, and settings for the selected workspace.", "method": "DELETE", "path": "/api/privacy/erase", "permission": "privacy:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "erased": { "type": "boolean", "const": true }, "projects": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "exports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "media": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "erased", "projects", "exports", "media" ], "additionalProperties": false }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-design&action=privacy.erase", "resource": { "kind": "workspace", "idPath": "$.workspaceId" }, "effects": [ "Permanently erases Design projects, export records, and generated R2 objects for the selected workspace." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again or provide a valid Topolo API key." }, { "status": 403, "code": "permission_denied", "recovery": "Grant the credential permission privacy:write and the required workspace binding." }, { "status": 422, "code": "invalid_input", "recovery": "Correct the payload using inputSchema, then validate before retrying." }, { "status": 429, "code": "rate_limited", "recovery": "Wait for Retry-After when present, then retry without parallel duplicate calls." }, { "status": 503, "code": "dependency_unavailable", "recovery": "Retry the action. If it continues, inspect the structured error details using the request ID." } ], "verify": [ "Call app_topolo_design.privacy.export and confirm both projects and exports are empty." ], "examples": [ { "input": { "confirmation": "ERASE" }, "expected": "A response matching the published outputSchema for privacy.erase." } ], "recovery": { "mode": "irreversible", "instructions": "No rollback is available. Export the workspace first if its Design records must be retained." }, "contractSource": "design-action-metadata" }, "documentation": { "example_input": { "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-design --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/privacy/erase", "body": null }, "effects": "Permanently erases Design projects, export records, and generated R2 objects for the selected workspace.", "verification": [ "Call app_topolo_design.privacy.export and confirm both projects and exports are empty." ], "recovery": [ { "mode": "irreversible", "instructions": "No rollback is available. Export the workspace first if its Design records must be retained." }, "401 authentication_required: Authenticate again or provide a valid Topolo API key.", "403 permission_denied: Grant the credential permission privacy:write and the required workspace binding.", "422 invalid_input: Correct the payload using inputSchema, then validate before retrying.", "429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls.", "503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-design&action=privacy.erase", "resource": { "kind": "workspace", "idPath": "$.workspaceId" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/privacy/erase", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 44, "matched_actions": 36, "declared_unserved_actions": [ "DELETE /api/folders/*", "PATCH /api/folders/*" ], "coverage_excluded_actions": [], "uncatalogued_routes": [ { "key": "DELETE /api/folders", "method": "DELETE", "path": "/api/folders", "source": "apps/api/src/design-routes.ts", "target": "api" }, { "key": "PATCH /api/folders", "method": "PATCH", "path": "/api/folders", "source": "apps/api/src/design-routes.ts", "target": "api" } ], "ignored_routes": 6, "configured_exclusions": 4, "configuration_findings": [], "notes": [ "14 manually-declared route(s)" ] }, "runtime_contract_audit": { "status": "verified", "actions": 38, "contracts": 38, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/worker.ts" ], "authorization_sources": [ "apps/api/src/worker.ts" ], "findings": [] } } ], "mobile_contracts": [], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "LITERAL", "path": "/api/privacy/export", "source_path": "apps/TopoloDesign/apps/api/src/design-routes.ts" }, { "method": "ALL", "path": "*", "source_path": "apps/TopoloDesign/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/health", "source_path": "apps/TopoloDesign/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/app-identity", "source_path": "apps/TopoloDesign/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/widget", "source_path": "apps/TopoloDesign/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/bootstrap", "source_path": "apps/TopoloDesign/apps/api/src/worker.ts" } ], "ui_routes": [ { "path": "/getting-started", "source_path": "apps/TopoloDesign/apps/web/src/App.tsx" }, { "path": "/app/templates", "source_path": "apps/TopoloDesign/apps/web/src/app-routes.tsx" }, { "path": "/app/library", "source_path": "apps/TopoloDesign/apps/web/src/app-routes.tsx" }, { "path": "/app/media", "source_path": "apps/TopoloDesign/apps/web/src/app-routes.tsx" }, { "path": "/app/settings", "source_path": "apps/TopoloDesign/apps/web/src/app-routes.tsx" }, { "path": "/app/settings/:section", "source_path": "apps/TopoloDesign/apps/web/src/app-routes.tsx" }, { "path": "/app/projects/:projectId", "source_path": "apps/TopoloDesign/apps/web/src/app-routes.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloDesign/apps/web/src/app-routes.tsx" }, { "path": "/app/settings/workspace", "source_path": "apps/TopoloDesign/apps/web/src/routes/SettingsRoute.tsx" }, { "path": "/app/settings/brand", "source_path": "apps/TopoloDesign/apps/web/src/routes/SettingsRoute.tsx" }, { "path": "/app/settings/export", "source_path": "apps/TopoloDesign/apps/web/src/routes/SettingsRoute.tsx" }, { "path": "/app/settings/api-keys", "source_path": "apps/TopoloDesign/apps/web/src/routes/SettingsRoute.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/design", "internal/apps/design" ], "present_paths": [ "applications/design", "internal/apps/design" ], "missing_paths": [], "human_reference": "/systems/topolo-design", "machine_reference": "/machine/systems/topolo-design.json", "action_examples": 38, "action_schemas": 38 }, "source_findings": [ { "type": "declared_unserved_actions", "source_path": "apps/TopoloDesign/topolo.app.json", "detail": [ "DELETE /api/folders/*", "PATCH /api/folders/*" ] }, { "type": "uncatalogued_routes", "source_path": "apps/TopoloDesign/topolo.app.json", "detail": [ { "key": "DELETE /api/folders", "method": "DELETE", "path": "/api/folders", "source": "apps/api/src/design-routes.ts", "target": "api" }, { "key": "PATCH /api/folders", "method": "PATCH", "path": "/api/folders", "source": "apps/api/src/design-routes.ts", "target": "api" } ] } ] }, "topolo-developers": { "id": "topolo-developers", "name": "Topolo Developers", "slug": "topolo-developers", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloDevelopers" ], "source_revisions": [ { "source_path": "apps/TopoloDevelopers", "repository": "apps/TopoloDevelopers", "revision": "690f230abf462c7a526b16186b94b7fc05e210dd", "ref": "origin/staging" } ], "source_counts": { "source_files": 153, "test_files": 116, "test_cases": 0, "migration_files": 0, "database_tables": 0, "manifests": 1, "deploy_targets": 3, "actions": 59, "mobile_contracts": 1, "notifications": 7, "package_manifests": 2, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloDevelopers/topolo.app.json", "service_slug": "topolo-developers", "name": "topolo-developers", "app_id": "app_topolo_developers", "compatibility_date": "2026-07-11", "primary_target": "web", "environments": [ "development", "production", "staging" ], "targets": [ { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/worker.ts", "worker_name": "topolo-developers-api", "subdomain": null, "healthcheck_path": "/api/health", "variable_names": [ "AUTH_API_URL", "AUTH_APP_ID", "DEVELOPERS_PUBLIC_BASE_URL", "ENVIRONMENT", "P2P_API_URL", "P2P_APP_ID", "PLATFORM_DEVELOPER_ORGANIZATION_ID", "TOPOLO_NOTIFY_URL", "TOPOLO_SEED_APP_ID" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "AUTH_SERVICE", "target": null }, { "kind": "services", "binding": "AUTH_SERVICE", "target": null }, { "kind": "services", "binding": "AUTH_SERVICE", "target": null }, { "kind": "d1", "binding": "DEVELOPERS_CONTROL_DB", "target": null }, { "kind": "d1", "binding": "DEVELOPERS_CATALOG_DB", "target": null }, { "kind": "d1", "binding": "DEVELOPERS_INTEGRATIONS_DB", "target": null }, { "kind": "d1", "binding": "DEVELOPERS_ARTIFACTS_DB", "target": null }, { "kind": "d1", "binding": "DEVELOPERS_INTAKE_DB", "target": null }, { "kind": "r2", "binding": "MOBILE_ARTIFACTS", "target": null }, { "kind": "durableObjects", "binding": "ACTION_CATALOG_PARTITIONS", "target": null }, { "kind": "durableObjects", "binding": "APPLICATION_CATALOG_PARTITIONS", "target": null }, { "kind": "vectorize", "binding": "VECTORIZE", "target": null }, { "kind": "ai", "binding": "AI", "target": null } ] }, { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-developers", "subdomain": "developers", "healthcheck_path": "/api/health", "variable_names": [ "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null } ] }, { "name": "jobs", "kind": "worker", "directory": "apps/jobs", "main": "src/index.ts", "worker_name": "topolo-catalog-cron", "subdomain": null, "healthcheck_path": null, "variable_names": [ "AUTH_API_URL", "CATALOG_EMBEDDINGS_URL", "NEXUS_GATEWAY_URL" ], "secret_names": [], "bindings": [] } ], "notifications": [ "developers.app.approved", "developers.app.published", "developers.app.rejected", "developers.app.submitted", "developers.build.completed", "developers.build.failed", "developers.catalog.sync_failed" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_developers", "events": [ { "type": "developers.app.approved", "version": 1, "description": "A persisted marketplace review approved a developer application.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "app_id", "app_name", "status", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "success" }, "category": { "const": "developers" }, "object_type": { "const": "app" }, "object_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 }, "app_name": { "type": "string", "minLength": 1 }, "status": { "const": "approved" }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "App approved: Example", "body": "Your application passed marketplace review.", "surface": "notification", "priority": "normal", "severity": "success", "category": "developers", "object_type": "app", "object_id": "app_123", "app_id": "app_123", "app_name": "Example", "status": "approved", "cta_url": "https://developers.topolo.app/apps/app_123", "cta_label": "Open app", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^developers:submission:" } }, { "type": "developers.app.published", "version": 1, "description": "Developers durably published an application manifest into the live catalog.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "app_id", "app_name", "status", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "success" }, "category": { "const": "developers" }, "object_type": { "const": "app" }, "object_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 }, "app_name": { "type": "string", "minLength": 1 }, "status": { "const": "published" }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "App published: Example", "body": "Your application is published in the Topolo catalog.", "surface": "notification", "priority": "normal", "severity": "success", "category": "developers", "object_type": "app", "object_id": "app_123", "app_id": "app_123", "app_name": "Example", "status": "published", "cta_url": "https://developers.topolo.app/apps/app_123", "cta_label": "Open app", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^developers:app:" } }, { "type": "developers.app.rejected", "version": 1, "description": "A persisted marketplace review rejected a developer application.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "app_name", "status", "failure_reason", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "action" }, "priority": { "const": "high" }, "severity": { "const": "warning" }, "category": { "const": "developers" }, "object_type": { "const": "app" }, "object_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 }, "app_name": { "type": "string", "minLength": 1 }, "status": { "const": "rejected" }, "failure_reason": { "type": "string", "minLength": 5 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "App rejected: Example", "body": "Missing required evidence.", "surface": "action", "priority": "high", "severity": "warning", "category": "developers", "object_type": "app", "object_id": "app_123", "app_id": "app_123", "app_name": "Example", "status": "rejected", "failure_reason": "Missing required evidence.", "cta_url": "https://developers.topolo.app/apps/app_123", "cta_label": "Open app", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "confidential", "sensitiveFields": [ "body", "failure_reason" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^developers:submission:" } }, { "type": "developers.app.submitted", "version": 1, "description": "A developer application submission was durably persisted for marketplace review.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "app_id", "app_name", "status", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "info" }, "category": { "const": "developers" }, "object_type": { "const": "app" }, "object_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 }, "app_name": { "type": "string", "minLength": 1 }, "status": { "const": "pending" }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "App submitted: Example", "body": "Your application was submitted for marketplace review.", "surface": "notification", "priority": "normal", "severity": "info", "category": "developers", "object_type": "app", "object_id": "app_123", "app_id": "app_123", "app_name": "Example", "status": "pending", "cta_url": "https://developers.topolo.app/apps/app_123", "cta_label": "Open app", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^developers:app:" } }, { "type": "developers.build.completed", "version": 1, "description": "A persisted developer build request reached the completed state.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "build_request_id", "build_title", "status", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "success" }, "category": { "const": "developers" }, "object_type": { "const": "build_request" }, "object_id": { "type": "string", "minLength": 1 }, "build_request_id": { "type": "string", "minLength": 1 }, "build_title": { "type": "string", "minLength": 1 }, "status": { "const": "completed" }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Build completed: Queue monitor", "body": "Your requested build is complete.", "surface": "notification", "priority": "normal", "severity": "success", "category": "developers", "object_type": "build_request", "object_id": "req_123", "build_request_id": "req_123", "build_title": "Queue monitor", "status": "completed", "cta_url": "https://developers.topolo.app/requests", "cta_label": "Open build request", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "confidential", "sensitiveFields": [ "body", "build_title" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^developers:build:" } }, { "type": "developers.build.failed", "version": 1, "description": "A persisted developer build request reached the failed state.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "build_request_id", "build_title", "status", "failure_reason", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "action" }, "priority": { "const": "high" }, "severity": { "const": "critical" }, "category": { "const": "developers" }, "object_type": { "const": "build_request" }, "object_id": { "type": "string", "minLength": 1 }, "build_request_id": { "type": "string", "minLength": 1 }, "build_title": { "type": "string", "minLength": 1 }, "status": { "const": "failed" }, "failure_reason": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Build failed: Queue monitor", "body": "The build failed during validation.", "surface": "action", "priority": "high", "severity": "critical", "category": "developers", "object_type": "build_request", "object_id": "req_123", "build_request_id": "req_123", "build_title": "Queue monitor", "status": "failed", "failure_reason": "The build failed during validation.", "cta_url": "https://developers.topolo.app/requests", "cta_label": "Open build request", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "confidential", "sensitiveFields": [ "body", "build_title", "failure_reason" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^developers:build:" } }, { "type": "developers.catalog.sync_failed", "version": 1, "description": "Developers persisted a catalog publication failure after the live catalog sync failed.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "app_id", "app_name", "status", "failure_reason", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "action" }, "priority": { "const": "high" }, "severity": { "const": "critical" }, "category": { "const": "developers" }, "object_type": { "const": "catalog_sync" }, "object_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 }, "app_name": { "type": "string", "minLength": 1 }, "status": { "const": "failed" }, "failure_reason": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Catalog sync failed: Example", "body": "Permission publication failed.", "surface": "action", "priority": "high", "severity": "critical", "category": "developers", "object_type": "catalog_sync", "object_id": "catalog_failure_123", "app_id": "app_123", "app_name": "Example", "status": "failed", "failure_reason": "Permission publication failed.", "cta_url": "https://developers.topolo.app/apps/app_123", "cta_label": "Open app", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "confidential", "sensitiveFields": [ "body", "failure_reason" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^developers:catalog-sync:" } } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "workspace:read", "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-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "apps.list", "title": "List developer apps", "description": "List apps owned by the developer workspace.", "method": "GET", "path": "/api/developer-console/apps", "permission": "apps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List developer apps.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/apps", "body": null }, "effects": "Reads state through GET /api/developer-console/apps without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/apps", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.create", "title": "Create developer app", "description": "Create a developer app registration.", "method": "POST", "path": "/api/developer-console/apps", "permission": "apps:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "description": { "type": "string", "maxLength": 2000 }, "category": { "type": "string", "maxLength": 80 }, "distributionModel": { "type": "string", "enum": [ "marketplace", "organization_internal" ] }, "pricingType": { "type": "string", "enum": [ "free", "paid" ] }, "version": { "type": "string" }, "supportEmail": { "type": "string" }, "websiteUrl": { "type": "string" }, "demoUrl": { "type": "string" }, "repoUrl": { "type": "string" }, "notes": { "type": "string" }, "monthlyPrice": { "anyOf": [ { "type": "number" }, { "type": "string", "const": "" }, { "type": "null" } ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "screenshots": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "members": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "viewer" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "addedAt": { "type": "string" } }, "required": [ "email", "role" ], "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create developer app.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "name": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/apps", "body": { "name": "example" } }, "effects": "May change state through POST /api/developer-console/apps. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/apps", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.get", "title": "Get developer app", "description": "Get one developer app registration.", "method": "GET", "path": "/api/developer-console/apps/{appId}", "permission": "apps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get developer app.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/apps/example", "body": null }, "effects": "Reads state through GET /api/developer-console/apps/{appId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/apps/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.update", "title": "Update developer app", "description": "Update one developer app registration.", "method": "PATCH", "path": "/api/developer-console/apps/{appId}", "permission": "apps:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "distributionModel": { "type": "string", "enum": [ "marketplace", "organization_internal" ] }, "pricingType": { "type": "string", "enum": [ "free", "paid" ] }, "version": { "type": "string" }, "supportEmail": { "type": "string" }, "websiteUrl": { "type": "string" }, "demoUrl": { "type": "string" }, "repoUrl": { "type": "string" }, "notes": { "type": "string" }, "monthlyPrice": { "anyOf": [ { "type": "number" }, { "type": "string", "const": "" }, { "type": "null" } ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "screenshots": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "members": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "viewer" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "addedAt": { "type": "string" } }, "required": [ "email", "role" ], "additionalProperties": false } }, "appStatus": { "type": "string", "enum": [ "draft", "configured", "archived" ] } }, "required": [ "appId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update developer app.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/developer-console/apps/example", "body": { "appId": "example" } }, "effects": "May change state through PATCH /api/developer-console/apps/{appId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/developer-console/apps/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.submit", "title": "Submit developer app", "description": "Submit an app for review.", "method": "POST", "path": "/api/developer-console/apps/{appId}/submit", "permission": "submissions:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Submit developer app.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/apps/example/submit", "body": { "appId": "example" } }, "effects": "May change state through POST /api/developer-console/apps/{appId}/submit. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/apps/*/submit", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "build_requests.list", "title": "List build requests", "description": "List developer build requests.", "method": "GET", "path": "/api/developer-console/build-requests", "permission": "requests:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List build requests.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/build-requests", "body": null }, "effects": "Reads state through GET /api/developer-console/build-requests without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/build-requests", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "build_requests.create", "title": "Create build request", "description": "Submit a developer build request for a community or company application.", "method": "POST", "path": "/api/developer-console/build-requests", "permission": "requests:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestType": { "type": "string", "enum": [ "community", "company" ] }, "title": { "type": "string", "minLength": 4, "maxLength": 140 }, "summary": { "type": "string", "minLength": 20, "maxLength": 2000 }, "impact": { "type": "string", "maxLength": 1000 }, "budgetContext": { "type": "string", "maxLength": 500 } }, "required": [ "title", "summary" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create build request.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "title": "example", "summary": "examplexxxxxxxxxxxxx" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/build-requests", "body": { "title": "example", "summary": "examplexxxxxxxxxxxxx" } }, "effects": "May change state through POST /api/developer-console/build-requests. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/build-requests", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "review.submissions.list", "title": "List app submissions", "description": "List app submissions awaiting review.", "method": "GET", "path": "/api/developer-console/review/app-submissions", "permission": "review:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List app submissions.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/review/app-submissions", "body": null }, "effects": "Reads state through GET /api/developer-console/review/app-submissions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/review/app-submissions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "review.submissions.review", "title": "Review app submission", "description": "Review an app submission.", "method": "POST", "path": "/api/developer-console/review/app-submissions/{submissionId}/review", "permission": "review:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "submissionId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "pending", "in_review", "approved", "rejected", "requires_changes" ] }, "rejectionReason": { "type": "string", "maxLength": 1000 } }, "required": [ "submissionId", "status" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Review app submission.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "submissionId": "example", "status": "pending" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/review/app-submissions/example/review", "body": { "submissionId": "example", "status": "pending" } }, "effects": "May change state through POST /api/developer-console/review/app-submissions/{submissionId}/review. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/review/app-submissions/*/review", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "catalog.embeddings.sync", "title": "Sync catalog embeddings", "description": "Process one bounded page of stale, selected, or all catalog application embeddings.", "method": "POST", "path": "/api/catalog/embeddings", "permission": "marketplace:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "all": { "type": "boolean" }, "appId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "embedded": { "type": "integer" }, "failed": { "type": "integer" }, "scanned": { "type": "integer" }, "page": { "type": "object", "additionalProperties": true } }, "required": [ "ok", "embedded", "failed", "scanned", "page" ], "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "cursor": "2026-01-01", "limit": 1, "all": true }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/catalog/embeddings", "body": { "cursor": "2026-01-01", "limit": 1, "all": true } }, "effects": "May change state through POST /api/catalog/embeddings. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/catalog/embeddings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "catalog.registry.reconcile", "title": "Reconcile catalog registry projection", "description": "Republish one developer application into the public catalog projection.", "method": "POST", "path": "/api/internal/registry-reconcile", "permission": "marketplace:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "properties": { "source": { "type": "string", "const": "developer-apps" }, "operation": { "type": "string", "const": "registry-reconcile" }, "appId": { "type": "string", "minLength": 1 }, "total": { "type": "integer", "minimum": 0, "maximum": 1 }, "published": { "type": "integer", "minimum": 0, "maximum": 1 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 1 }, "skippedAppIds": { "type": "array", "items": { "type": "string" }, "maxItems": 1 }, "failed": { "type": "integer", "minimum": 0, "maximum": 1 }, "failures": { "type": "array", "items": { "type": "object", "properties": { "appId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "appId", "error" ], "additionalProperties": false }, "maxItems": 1 }, "page": { "type": "object", "properties": { "nextCursor": { "type": "null" }, "hasMore": { "type": "boolean", "const": false } }, "required": [ "nextCursor", "hasMore" ], "additionalProperties": false } }, "required": [ "source", "operation", "appId", "total", "published", "skipped", "skippedAppIds", "failed", "failures", "page" ], "additionalProperties": false }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/reference/actions?service=topolo-developers&action=catalog.registry.reconcile", "resource": { "kind": "catalog_application", "idPath": "$.appId" }, "effects": [ "Republishes the current developer application metadata into the public catalog projection for exactly one app." ], "examples": [ { "input": { "appId": "app_topolo_example" } } ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again with the intended Topolo environment." }, { "status": 403, "code": "permission_denied", "recovery": "Use a credential with marketplace:write permission for Topolo Developers." }, { "status": 422, "code": "invalid_input", "recovery": "Provide exactly one non-empty appId and validate the action before retrying." }, { "status": 502, "code": "registry_reconcile_failed", "recovery": "Inspect the returned failure for the selected app, correct its source metadata, and retry the unchanged appId." } ], "verify": [ "Call app_topolo_developers.catalog.search with q equal to the appId and confirm the returned catalog entry matches the current developer application metadata." ], "nextActionIds": [ "app_topolo_developers.catalog.search" ] }, "documentation": { "example_input": { "appId": "app_topolo_example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/internal/registry-reconcile", "body": { "appId": "app_topolo_example" } }, "effects": "Republishes the current developer application metadata into the public catalog projection for exactly one app.", "verification": [ "Call app_topolo_developers.catalog.search with q equal to the appId and confirm the returned catalog entry matches the current developer application metadata." ], "recovery": [ "401 authentication_required: Authenticate again with the intended Topolo environment.", "403 permission_denied: Use a credential with marketplace:write permission for Topolo Developers.", "422 invalid_input: Provide exactly one non-empty appId and validate the action before retrying.", "502 registry_reconcile_failed: Inspect the returned failure for the selected app, correct its source metadata, and retry the unchanged appId." ], "docs_url": "https://docs.topolo.app/reference/actions?service=topolo-developers&action=catalog.registry.reconcile", "resource": { "kind": "catalog_application", "idPath": "$.appId" }, "next_action_ids": [ "app_topolo_developers.catalog.search" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/internal/registry-reconcile", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "notifications.catalog.list", "title": "List notification contracts", "description": "Search the app-owned notification event and projection catalog.", "method": "GET", "path": "/api/catalog/notifications", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "type": "string" }, "app": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "deprecated" ] }, "deliveryClass": { "type": "string", "enum": [ "automation", "notification", "action", "transactional" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "required": [ "notifications", "count", "page" ], "properties": { "notifications": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "count": { "type": "integer" }, "page": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "public", "documentation": { "example_input": { "q": "example", "app": "example", "status": "draft" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/catalog/notifications", "body": null }, "effects": "Reads state through GET /api/catalog/notifications without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/catalog/notifications", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "catalog.search", "title": "Search app catalog", "description": "Search the live app catalog.", "method": "GET", "path": "/api/catalog/search", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 40 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Search app catalog.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "public", "documentation": { "example_input": { "q": "example", "limit": 1 }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/catalog/search", "body": null }, "effects": "Reads state through GET /api/catalog/search without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/catalog/search", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspace.summary.get", "title": "workspace summary get", "description": "Execute workspace.summary.get in Topolo Developers.", "target": "api", "method": "GET", "path": "/api/developer-console/summary", "permission": "apps:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/summary", "body": null }, "effects": "Reads state through GET /api/developer-console/summary without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/summary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspace.onboarding.get", "title": "workspace onboarding get", "description": "Execute workspace.onboarding.get in Topolo Developers.", "target": "api", "method": "GET", "path": "/api/developer-console/onboarding", "permission": "apps:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/onboarding", "body": null }, "effects": "Reads state through GET /api/developer-console/onboarding without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/onboarding", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspace.onboarding.update", "title": "workspace onboarding update", "description": "Execute workspace.onboarding.update in Topolo Developers.", "target": "api", "method": "PUT", "path": "/api/developer-console/onboarding", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "action": "example", "apiKeyResources": "example", "appDir": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/developer-console/onboarding", "body": { "action": "example", "apiKeyResources": "example", "appDir": "example" } }, "effects": "May change state through PUT /api/developer-console/onboarding. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/developer-console/onboarding", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.scaffold", "title": "apps scaffold", "description": "Execute apps.scaffold in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/apps/scaffold", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "action": "example", "apiKeyResources": "example", "appDir": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/apps/scaffold", "body": { "action": "example", "apiKeyResources": "example", "appDir": "example" } }, "effects": "May change state through POST /api/developer-console/apps/scaffold. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/apps/scaffold", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.reconcile", "title": "Reconcile application registration", "description": "Check or apply a declarative third-party application registration for the authenticated developer organization.", "target": "api", "method": "POST", "path": "/api/developer-console/apps/reconcile", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "mode": { "type": "string", "enum": [ "check", "apply" ] }, "healthcheckPath": {}, "callbackUrls": { "type": "array", "items": { "type": "string" } }, "requestedScopes": { "type": "array", "items": { "type": "string" } }, "capabilities": { "type": "array", "items": { "type": "string" } }, "marketplace": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "notifications": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "actions": { "type": "array", "maxItems": 250, "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "action": "example", "apiKeyResources": "example", "appDir": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/apps/reconcile", "body": { "action": "example", "apiKeyResources": "example", "appDir": "example" } }, "effects": "May change state through POST /api/developer-console/apps/reconcile. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/apps/reconcile", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.claim_transfer", "title": "apps claim transfer", "description": "Execute apps.claim_transfer in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/apps/claim-transfer", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "action": "example", "apiKeyResources": "example", "appDir": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/apps/claim-transfer", "body": { "action": "example", "apiKeyResources": "example", "appDir": "example" } }, "effects": "May change state through POST /api/developer-console/apps/claim-transfer. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/apps/claim-transfer", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.transfer", "title": "apps transfer", "description": "Execute apps.transfer in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/apps/{appId}/transfer", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/apps/example/transfer", "body": { "appId": "example" } }, "effects": "May change state through POST /api/developer-console/apps/{appId}/transfer. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/apps/*/transfer", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.icon.upload", "title": "apps icon upload", "description": "Execute apps.icon.upload in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/apps/{appId}/icon", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string", "minLength": 1, "maxLength": 350000 }, "contentType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp" ] }, "fileName": { "type": "string", "minLength": 1 } }, "required": [ "appId", "contentBase64", "contentType", "fileName" ], "additionalProperties": false }, "agentContract": { "upload": { "profile": "inline-base64", "contentField": "contentBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 262144, "acceptedContentTypes": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp" ] } }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example", "contentBase64": "example", "contentType": "image/svg+xml", "fileName": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/apps/example/icon", "body": { "appId": "example", "contentBase64": "example", "contentType": "image/svg+xml", "fileName": "example" } }, "effects": "May change state through POST /api/developer-console/apps/{appId}/icon. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/apps/*/icon", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.marketing.get", "title": "apps marketing get", "description": "Execute apps.marketing.get in Topolo Developers.", "target": "api", "method": "GET", "path": "/api/developer-console/apps/{appId}/marketing", "permission": "apps:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/apps/example/marketing", "body": null }, "effects": "Reads state through GET /api/developer-console/apps/{appId}/marketing without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/apps/*/marketing", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.marketing.update", "title": "apps marketing update", "description": "Execute apps.marketing.update in Topolo Developers.", "target": "api", "method": "PUT", "path": "/api/developer-console/apps/{appId}/marketing", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": { "type": "string", "minLength": 130, "maxLength": 200 }, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroMedia": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ] }, "src": { "type": "string", "format": "uri" }, "alt": { "type": "string", "minLength": 1, "maxLength": 240 }, "poster": { "type": "string", "format": "uri" }, "caption": { "type": "string", "maxLength": 400 } }, "required": [ "type", "src", "alt" ], "additionalProperties": false }, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": { "type": "string", "enum": [ "active", "preview", "platform", "community" ] }, "subcategory": { "type": "string" }, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "marketplaceCategory": { "type": "string" }, "stageLabel": { "type": "string" }, "surface": { "type": "string" }, "shortBlurb": { "type": "string" }, "tagline": { "type": "string" }, "problemStatement": { "type": "string" }, "solutionStatement": { "type": "string" }, "docsUrl": { "type": "string" }, "appUrl": { "type": "string" }, "gallery": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ] }, "src": { "type": "string", "format": "uri" }, "alt": { "type": "string", "minLength": 1, "maxLength": 240 }, "poster": { "type": "string", "format": "uri" }, "caption": { "type": "string", "maxLength": 400 } }, "required": [ "type", "src", "alt" ], "additionalProperties": false } }, "benefits": {}, "features": {}, "stats": {}, "gettingStarted": {}, "worksWellWith": {} }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/developer-console/apps/example/marketing", "body": { "appId": "example" } }, "effects": "May change state through PUT /api/developer-console/apps/{appId}/marketing. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/developer-console/apps/*/marketing", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.mobile_artifacts.list", "title": "apps mobile artifacts list", "description": "Execute apps.mobile_artifacts.list in Topolo Developers.", "target": "api", "method": "GET", "path": "/api/developer-console/apps/{appId}/mobile-artifacts", "permission": "apps:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/apps/example/mobile-artifacts", "body": null }, "effects": "Reads state through GET /api/developer-console/apps/{appId}/mobile-artifacts without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/apps/*/mobile-artifacts", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.mobile_artifacts.create", "title": "apps mobile artifacts create", "description": "Execute apps.mobile_artifacts.create in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/apps/{appId}/mobile-artifacts", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "enum": [ "android", "ios" ] }, "releaseTrack": { "type": "string", "minLength": 1, "maxLength": 60 }, "packageName": { "type": "string", "minLength": 1 }, "bundleId": { "type": "string", "minLength": 1 }, "versionName": { "type": "string", "minLength": 1, "maxLength": 40 }, "buildNumber": { "type": "string", "minLength": 1, "maxLength": 40 }, "artifactType": { "type": "string", "enum": [ "metadata", "apk", "aab", "ipa", "app_store", "testflight" ] }, "artifactUrl": { "type": "string", "format": "uri" }, "checksumSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "status": { "type": "string", "enum": [ "draft", "submitted", "approved", "published", "retired" ] }, "minimumOsVersion": { "type": "string", "minLength": 1, "maxLength": 40 }, "supportedDeviceClasses": { "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1 } }, "distributionChannel": { "type": "string", "minLength": 1, "maxLength": 60 }, "catalogCategory": { "type": "string", "enum": [ "system-apps", "topolo-store", "topolo-apps", "apkList" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "appId", "platform", "versionName", "artifactType" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example", "platform": "android", "versionName": "example", "artifactType": "metadata" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/apps/example/mobile-artifacts", "body": { "appId": "example", "platform": "android", "versionName": "example", "artifactType": "metadata" } }, "effects": "May change state through POST /api/developer-console/apps/{appId}/mobile-artifacts. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/apps/*/mobile-artifacts", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.native_mobile_experience.update", "title": "apps native mobile experience update", "description": "Execute apps.native_mobile_experience.update in Topolo Developers.", "target": "api", "method": "PUT", "path": "/api/developer-console/apps/{appId}/native-mobile-experience", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/developer-console/apps/example/native-mobile-experience", "body": { "appId": "example" } }, "effects": "May change state through PUT /api/developer-console/apps/{appId}/native-mobile-experience. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/developer-console/apps/*/native-mobile-experience", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.native_mobile_experience.delete", "title": "apps native mobile experience delete", "description": "Execute apps.native_mobile_experience.delete in Topolo Developers.", "target": "api", "method": "DELETE", "path": "/api/developer-console/apps/{appId}/native-mobile-experience", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/developer-console/apps/example/native-mobile-experience", "body": null }, "effects": "May change state through DELETE /api/developer-console/apps/{appId}/native-mobile-experience. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/developer-console/apps/*/native-mobile-experience", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.actions.list", "title": "apps actions list", "description": "Execute apps.actions.list in Topolo Developers.", "target": "api", "method": "GET", "path": "/api/developer-console/apps/{appId}/actions", "permission": "apps:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/apps/example/actions", "body": null }, "effects": "Reads state through GET /api/developer-console/apps/{appId}/actions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/apps/*/actions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.actions.create", "title": "apps actions create", "description": "Execute apps.actions.create in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/apps/{appId}/actions", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/apps/example/actions", "body": { "appId": "example" } }, "effects": "May change state through POST /api/developer-console/apps/{appId}/actions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/apps/*/actions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.actions.publish", "title": "apps actions publish", "description": "Execute apps.actions.publish in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/apps/{appId}/actions/{actionId}/publish", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": { "type": "string", "minLength": 1 }, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId", "actionId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example", "actionId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/apps/example/actions/example/publish", "body": { "appId": "example", "actionId": "example" } }, "effects": "May change state through POST /api/developer-console/apps/{appId}/actions/{actionId}/publish. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/apps/*/actions/*/publish", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.api_key_resources.list", "title": "apps api key resources list", "description": "Execute apps.api_key_resources.list in Topolo Developers.", "target": "api", "method": "GET", "path": "/api/developer-console/apps/{appId}/api-key-resources", "permission": "apps:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/apps/example/api-key-resources", "body": null }, "effects": "Reads state through GET /api/developer-console/apps/{appId}/api-key-resources without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/apps/*/api-key-resources", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.api_key_resources.update", "title": "apps api key resources update", "description": "Execute apps.api_key_resources.update in Topolo Developers.", "target": "api", "method": "PUT", "path": "/api/developer-console/apps/{appId}/api-key-resources", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/developer-console/apps/example/api-key-resources", "body": { "appId": "example" } }, "effects": "May change state through PUT /api/developer-console/apps/{appId}/api-key-resources. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/developer-console/apps/*/api-key-resources", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.api_key_resources.publish", "title": "apps api key resources publish", "description": "Execute apps.api_key_resources.publish in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/apps/{appId}/api-key-resources/publish", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/apps/example/api-key-resources/publish", "body": { "appId": "example" } }, "effects": "May change state through POST /api/developer-console/apps/{appId}/api-key-resources/publish. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/apps/*/api-key-resources/publish", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.p2p_capabilities.list", "title": "apps p2p capabilities list", "description": "Execute apps.p2p_capabilities.list in Topolo Developers.", "target": "api", "method": "GET", "path": "/api/developer-console/apps/{appId}/p2p-capabilities", "permission": "apps:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/apps/example/p2p-capabilities", "body": null }, "effects": "Reads state through GET /api/developer-console/apps/{appId}/p2p-capabilities without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/apps/*/p2p-capabilities", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.p2p_capabilities.create", "title": "apps p2p capabilities create", "description": "Execute apps.p2p_capabilities.create in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/apps/{appId}/p2p-capabilities", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "pricingModel": {}, "pricingAmountMinor": {}, "currency": {}, "supportedContexts": {}, "trustLevel": {} }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/apps/example/p2p-capabilities", "body": { "appId": "example" } }, "effects": "May change state through POST /api/developer-console/apps/{appId}/p2p-capabilities. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/apps/*/p2p-capabilities", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.p2p_capabilities.update", "title": "apps p2p capabilities update", "description": "Execute apps.p2p_capabilities.update in Topolo Developers.", "target": "api", "method": "PUT", "path": "/api/developer-console/apps/{appId}/p2p-capabilities/{capabilityId}", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": { "type": "string", "minLength": 1 }, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "pricingModel": {}, "pricingAmountMinor": {}, "currency": {}, "supportedContexts": {}, "trustLevel": {} }, "required": [ "appId", "capabilityId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example", "capabilityId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/developer-console/apps/example/p2p-capabilities/example", "body": { "appId": "example", "capabilityId": "example" } }, "effects": "May change state through PUT /api/developer-console/apps/{appId}/p2p-capabilities/{capabilityId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/developer-console/apps/*/p2p-capabilities/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.p2p_capabilities.sync", "title": "apps p2p capabilities sync", "description": "Execute apps.p2p_capabilities.sync in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/apps/{appId}/p2p-capabilities/{capabilityId}/sync", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": { "type": "string", "minLength": 1 }, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId", "capabilityId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "appId": "example", "capabilityId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/apps/example/p2p-capabilities/example/sync", "body": { "appId": "example", "capabilityId": "example" } }, "effects": "May change state through POST /api/developer-console/apps/{appId}/p2p-capabilities/{capabilityId}/sync. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/apps/*/p2p-capabilities/*/sync", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "review.build_requests.list", "title": "review build requests list", "description": "Execute review.build_requests.list in Topolo Developers.", "target": "api", "method": "GET", "path": "/api/developer-console/review/build-requests", "permission": "review:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/review/build-requests", "body": null }, "effects": "Reads state through GET /api/developer-console/review/build-requests without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/review/build-requests", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "review.build_requests.review", "title": "review build requests review", "description": "Execute review.build_requests.review in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/review/build-requests/{requestId}/review", "permission": "review:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": { "type": "string", "minLength": 1 }, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "requestId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "requestId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/review/build-requests/example/review", "body": { "requestId": "example" } }, "effects": "May change state through POST /api/developer-console/review/build-requests/{requestId}/review. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/review/build-requests/*/review", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.marketplace.summary.get", "title": "admin marketplace summary get", "description": "Execute admin.marketplace.summary.get in Topolo Developers.", "target": "api", "method": "GET", "path": "/api/developer-console/admin/marketplace/summary", "permission": "marketplace:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "developersCursor": { "type": "string" }, "appsCursor": { "type": "string" }, "payoutAccountsCursor": { "type": "string" }, "payoutEventsCursor": { "type": "string" } }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "off", "documentation": { "example_input": { "limit": 1, "developersCursor": "example", "appsCursor": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/admin/marketplace/summary", "body": null }, "effects": "Reads state through GET /api/developer-console/admin/marketplace/summary without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/admin/marketplace/summary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.developers.update", "title": "admin developers update", "description": "Execute admin.developers.update in Topolo Developers.", "target": "api", "method": "PUT", "path": "/api/developer-console/admin/developers/{developerId}", "permission": "marketplace:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": { "type": "string", "minLength": 1 }, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "reviewState": {} }, "required": [ "developerId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "off", "documentation": { "example_input": { "developerId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/developer-console/admin/developers/example", "body": { "developerId": "example" } }, "effects": "May change state through PUT /api/developer-console/admin/developers/{developerId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/developer-console/admin/developers/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.platform_app_scaffolds.create", "title": "admin platform app scaffolds create", "description": "Execute admin.platform_app_scaffolds.create in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/admin/platform-app-scaffolds", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "off", "documentation": { "example_input": { "action": "example", "apiKeyResources": "example", "appDir": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/admin/platform-app-scaffolds", "body": { "action": "example", "apiKeyResources": "example", "appDir": "example" } }, "effects": "May change state through POST /api/developer-console/admin/platform-app-scaffolds. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/admin/platform-app-scaffolds", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.first_party_app_scaffolds.create", "title": "admin first party app scaffolds create", "description": "Execute admin.first_party_app_scaffolds.create in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/admin/first-party-app-scaffolds", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "off", "documentation": { "example_input": { "action": "example", "apiKeyResources": "example", "appDir": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/admin/first-party-app-scaffolds", "body": { "action": "example", "apiKeyResources": "example", "appDir": "example" } }, "effects": "May change state through POST /api/developer-console/admin/first-party-app-scaffolds. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/admin/first-party-app-scaffolds", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.apps.reconcile", "title": "Reconcile first-party application registration", "description": "Check or apply a declarative first-party application registration and its catalog and Auth projections.", "target": "api", "method": "POST", "path": "/api/developer-console/admin/apps/reconcile", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "mode": { "type": "string", "enum": [ "check", "apply" ] }, "healthcheckPath": {}, "callbackUrls": { "type": "array", "items": { "type": "string" } }, "requestedScopes": { "type": "array", "items": { "type": "string" } }, "capabilities": { "type": "array", "items": { "type": "string" } }, "marketplace": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "notifications": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "actions": { "type": "array", "maxItems": 250, "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "off", "documentation": { "example_input": { "action": "example", "apiKeyResources": "example", "appDir": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/admin/apps/reconcile", "body": { "action": "example", "apiKeyResources": "example", "appDir": "example" } }, "effects": "May change state through POST /api/developer-console/admin/apps/reconcile. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/admin/apps/reconcile", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.apps.catalog_projection.delete", "title": "Retire orphan application catalog registration", "description": "Archive an exactly matched orphan developer application when explicitly requested, then permanently remove its public catalog directory row and per-app manifest partition.", "target": "api", "method": "DELETE", "path": "/api/developer-console/admin/apps/{appId}/catalog-projection", "permission": "apps:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "expectedSlug": { "type": "string", "minLength": 1 }, "archiveActive": { "description": "Must be true to archive a matching active developer application before its public catalog projection is removed.", "type": "boolean" } }, "required": [ "appId", "expectedSlug" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": true, "requiresConfirmation": true, "agentAccess": "off", "documentation": { "example_input": { "appId": "example", "expectedSlug": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/developer-console/admin/apps/example/catalog-projection", "body": null }, "effects": "May change state through DELETE /api/developer-console/admin/apps/{appId}/catalog-projection. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/developer-console/admin/apps/*/catalog-projection", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.apps.marketing.update", "title": "admin apps marketing update", "description": "Execute admin.apps.marketing.update in Topolo Developers.", "target": "api", "method": "PUT", "path": "/api/developer-console/admin/apps/{appId}/marketing", "permission": "marketplace:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": { "type": "string", "minLength": 130, "maxLength": 200 }, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroMedia": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ] }, "src": { "type": "string", "format": "uri" }, "alt": { "type": "string", "minLength": 1, "maxLength": 240 }, "poster": { "type": "string", "format": "uri" }, "caption": { "type": "string", "maxLength": 400 } }, "required": [ "type", "src", "alt" ], "additionalProperties": false }, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": { "type": "string", "enum": [ "active", "preview", "platform", "community" ] }, "subcategory": { "type": "string" }, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "marketplaceCategory": { "type": "string" }, "stageLabel": { "type": "string" }, "surface": { "type": "string" }, "shortBlurb": { "type": "string" }, "tagline": { "type": "string" }, "problemStatement": { "type": "string" }, "solutionStatement": { "type": "string" }, "docsUrl": { "type": "string" }, "appUrl": { "type": "string" }, "gallery": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ] }, "src": { "type": "string", "format": "uri" }, "alt": { "type": "string", "minLength": 1, "maxLength": 240 }, "poster": { "type": "string", "format": "uri" }, "caption": { "type": "string", "maxLength": 400 } }, "required": [ "type", "src", "alt" ], "additionalProperties": false } }, "benefits": {}, "features": {}, "stats": {}, "gettingStarted": {}, "worksWellWith": {} }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "off", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/developer-console/admin/apps/example/marketing", "body": { "appId": "example" } }, "effects": "May change state through PUT /api/developer-console/admin/apps/{appId}/marketing. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/developer-console/admin/apps/*/marketing", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.apps.marketplace.update", "title": "admin apps marketplace update", "description": "Execute admin.apps.marketplace.update in Topolo Developers.", "target": "api", "method": "PUT", "path": "/api/developer-console/admin/apps/{appId}/marketplace", "permission": "marketplace:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": { "anyOf": [ { "type": "number" }, { "type": "string", "const": "" }, { "type": "null" } ] }, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": { "type": "string", "enum": [ "included", "free", "paid", "request", "external" ] }, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "billingInterval": { "type": "string", "enum": [ "monthly", "annual", "one_time" ] }, "priceLabel": { "type": "string", "maxLength": 80 }, "catalogListingState": { "type": "string", "enum": [ "draft", "developer_only", "internal", "unlisted", "public", "retired" ] }, "runtimeState": { "type": "string", "enum": [ "healthy", "disabled", "sunset" ] }, "checkoutStatus": { "type": "string", "enum": [ "not_configured", "ready", "blocked" ] }, "platformFeeBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "appId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "off", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/developer-console/admin/apps/example/marketplace", "body": { "appId": "example" } }, "effects": "May change state through PUT /api/developer-console/admin/apps/{appId}/marketplace. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/developer-console/admin/apps/*/marketplace", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.payout_accounts.update", "title": "admin payout accounts update", "description": "Execute admin.payout_accounts.update in Topolo Developers.", "target": "api", "method": "PUT", "path": "/api/developer-console/admin/payout-accounts/{developerId}", "permission": "marketplace:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": { "type": "string", "minLength": 1 }, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "provider": {}, "accountReference": {}, "defaultCurrency": {}, "payoutSchedule": {} }, "required": [ "developerId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "off", "documentation": { "example_input": { "developerId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/developer-console/admin/payout-accounts/example", "body": { "developerId": "example" } }, "effects": "May change state through PUT /api/developer-console/admin/payout-accounts/{developerId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/developer-console/admin/payout-accounts/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.payout_events.create", "title": "admin payout events create", "description": "Execute admin.payout_events.create in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/admin/payout-events", "permission": "marketplace:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "eventType": {}, "amount": {}, "currency": {} }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "off", "documentation": { "example_input": { "action": "example", "apiKeyResources": "example", "appDir": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/admin/payout-events", "body": { "action": "example", "apiKeyResources": "example", "appDir": "example" } }, "effects": "May change state through POST /api/developer-console/admin/payout-events. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/admin/payout-events", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.catalog.get", "title": "admin catalog get", "description": "Execute admin.catalog.get in Topolo Developers.", "target": "api", "method": "GET", "path": "/api/developer-console/admin/catalog", "permission": "marketplace:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "resource": { "type": "string", "enum": [ "collections", "apps" ] }, "cursor": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "query": { "type": "string" } }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "off", "documentation": { "example_input": { "resource": "collections", "cursor": "example", "limit": 1 }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/admin/catalog", "body": null }, "effects": "Reads state through GET /api/developer-console/admin/catalog without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/admin/catalog", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.catalog.collections.create", "title": "admin catalog collections create", "description": "Execute admin.catalog.collections.create in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/admin/catalog/collections", "permission": "marketplace:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "off", "documentation": { "example_input": { "action": "example", "apiKeyResources": "example", "appDir": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/admin/catalog/collections", "body": { "action": "example", "apiKeyResources": "example", "appDir": "example" } }, "effects": "May change state through POST /api/developer-console/admin/catalog/collections. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/admin/catalog/collections", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.catalog.collections.update", "title": "admin catalog collections update", "description": "Execute admin.catalog.collections.update in Topolo Developers.", "target": "api", "method": "PUT", "path": "/api/developer-console/admin/catalog/collections/{collectionId}", "permission": "marketplace:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": { "type": "string", "minLength": 1 }, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "collectionId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "off", "documentation": { "example_input": { "collectionId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/developer-console/admin/catalog/collections/example", "body": { "collectionId": "example" } }, "effects": "May change state through PUT /api/developer-console/admin/catalog/collections/{collectionId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/developer-console/admin/catalog/collections/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.catalog.collections.apps.list", "title": "admin catalog collections apps list", "description": "Execute admin.catalog.collections.apps.list in Topolo Developers.", "target": "api", "method": "GET", "path": "/api/developer-console/admin/catalog/collections/{collectionId}/apps", "permission": "marketplace:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "collectionId": { "type": "string", "minLength": 1 }, "cursor": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "query": { "type": "string" } }, "required": [ "collectionId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "off", "documentation": { "example_input": { "collectionId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/admin/catalog/collections/example/apps", "body": null }, "effects": "Reads state through GET /api/developer-console/admin/catalog/collections/{collectionId}/apps without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/admin/catalog/collections/*/apps", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.catalog.collections.apps.add", "title": "admin catalog collections apps add", "description": "Execute admin.catalog.collections.apps.add in Topolo Developers.", "target": "api", "method": "POST", "path": "/api/developer-console/admin/catalog/collections/{collectionId}/apps", "permission": "marketplace:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": { "type": "string", "minLength": 1 }, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "collectionId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "off", "documentation": { "example_input": { "collectionId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/developer-console/admin/catalog/collections/example/apps", "body": { "collectionId": "example" } }, "effects": "May change state through POST /api/developer-console/admin/catalog/collections/{collectionId}/apps. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/developer-console/admin/catalog/collections/*/apps", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.catalog.collections.apps.remove", "title": "admin catalog collections apps remove", "description": "Execute admin.catalog.collections.apps.remove in Topolo Developers.", "target": "api", "method": "DELETE", "path": "/api/developer-console/admin/catalog/collections/{collectionId}/apps/{appId}", "permission": "marketplace:write", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": { "type": "string", "minLength": 1 }, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId", "collectionId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": true, "requiresConfirmation": true, "agentAccess": "off", "documentation": { "example_input": { "appId": "example", "collectionId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/developer-console/admin/catalog/collections/example/apps/example", "body": null }, "effects": "May change state through DELETE /api/developer-console/admin/catalog/collections/{collectionId}/apps/{appId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/developer-console/admin/catalog/collections/*/apps/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.data.export", "title": "Export workspace data", "description": "Export the selected workspace data owned by Topolo Developers with credential fields redacted.", "target": "api", "method": "GET", "path": "/api/developer-console/workspaces/{workspaceId}/data", "permission": "workspace:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/developer-console/workspaces/example/data", "body": null }, "effects": "Reads state through GET /api/developer-console/workspaces/{workspaceId}/data without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/developer-console/workspaces/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.data.erase", "title": "Erase workspace data", "description": "Permanently erase the selected workspace data and derived projections owned by Topolo Developers.", "target": "api", "method": "DELETE", "path": "/api/developer-console/workspaces/{workspaceId}/data", "permission": "workspace:delete", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/developer-console/workspaces/example/data", "body": null }, "effects": "May change state through DELETE /api/developer-console/workspaces/{workspaceId}/data. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/developer-console/workspaces/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "workspaces delete", "description": "Manage app-local workspaces in Topolo Developers.", "target": "api", "method": "DELETE", "path": "/api/developer-console/workspaces/{workspaceId}", "permission": "workspace:delete", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-developers --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/developer-console/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/developer-console/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/developer-console/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 75, "matched_actions": 59, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 16, "configured_exclusions": 17, "configuration_findings": [ "* /api/*: exclusion matches no served route", "* /run: exclusion matches no served route" ], "notes": [ "no routes extracted from jobs", "54 manually-declared route(s)" ] }, "runtime_contract_audit": { "status": "verified", "actions": 59, "contracts": 59, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/worker.ts" ], "authorization_sources": [ "apps/api/src/worker.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloDevelopers/topolo.mobile-experience.json", "contract": { "version": "2026-07-03", "status": "approved", "mode": "web", "webOnly": true, "appId": "app_topolo_developers", "localizationNamespace": "developers", "fallbackPath": "/overview", "notes": "TopoloDevelopers is the developer portal and catalog/registry control plane (OAuth clients, API credentials, app submissions, review queues, catalog admin, registry reconcile). It is a desktop developer-tooling surface with no first-class mobile use case; it deliberately does not ship a native dynamic-app experience. webOnly opts it out of the TopoloOne native shell while keeping it web-accessible." } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "ALL", "path": "*", "source_path": "apps/TopoloDevelopers/apps/api/src/worker.ts" } ], "ui_routes": [ { "path": "/api/widget", "source_path": "apps/TopoloDevelopers/apps/api/src/action-contracts.js" }, { "path": "/api/developer-console/apps", "source_path": "apps/TopoloDevelopers/apps/api/src/action-contracts.js" }, { "path": "/api/developer-console/apps/{appId}", "source_path": "apps/TopoloDevelopers/apps/api/src/action-contracts.js" }, { "path": "/api/developer-console/apps/{appId}/submit", "source_path": "apps/TopoloDevelopers/apps/api/src/action-contracts.js" }, { "path": "/api/developer-console/build-requests", "source_path": "apps/TopoloDevelopers/apps/api/src/action-contracts.js" }, { "path": "/api/developer-console/review/app-submissions", "source_path": "apps/TopoloDevelopers/apps/api/src/action-contracts.js" }, { "path": "/api/developer-console/review/app-submissions/{submissionId}/review", "source_path": "apps/TopoloDevelopers/apps/api/src/action-contracts.js" }, { "path": "/api/catalog/embeddings", "source_path": "apps/TopoloDevelopers/apps/api/src/action-contracts.js" }, { "path": "/api/internal/registry-reconcile", "source_path": "apps/TopoloDevelopers/apps/api/src/action-contracts.js" }, { "path": "/api/catalog/search", "source_path": "apps/TopoloDevelopers/apps/api/src/action-contracts.js" }, { "path": "/api/catalog/notifications", "source_path": "apps/TopoloDevelopers/apps/api/src/action-contracts.js" }, { "path": "/mobile/actions", "source_path": "apps/TopoloDevelopers/apps/api/src/registry/reconcile.ts" }, { "path": "/overview", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/onboarding", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/apps", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/apps/:appId", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/notifications", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/credentials", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/developers/oauth-clients", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/requests", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/admin/apps", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/admin/catalog", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/admin/payouts", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/review/app-submissions", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/review/build-requests", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/settings", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/settings/:section", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/signup", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" }, { "path": "/developers/oauth/consent", "source_path": "apps/TopoloDevelopers/apps/web/src/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/developers", "internal/apps/topolo-developers" ], "present_paths": [ "applications/developers", "internal/apps/topolo-developers" ], "missing_paths": [], "human_reference": "/systems/topolo-developers", "machine_reference": "/machine/systems/topolo-developers.json", "action_examples": 59, "action_schemas": 59 }, "source_findings": [ { "type": "action_coverage_configuration", "source_path": "apps/TopoloDevelopers/topolo.app.json", "detail": [ "* /api/*: exclusion matches no served route", "* /run: exclusion matches no served route" ] } ] }, "topolo-device-platform": { "id": "topolo-device-platform", "name": "Topolo Device Platform", "slug": "topolo-device-platform", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloFeed" ], "source_revisions": [ { "source_path": "apps/TopoloFeed", "repository": "apps/TopoloFeed", "revision": "deab96cb4917fd854dbd9f87e2bf944b242ce2c5", "ref": "origin/staging" } ], "source_counts": { "source_files": 56, "test_files": 34, "test_cases": 0, "migration_files": 15, "database_tables": 0, "manifests": 1, "deploy_targets": 3, "actions": 14, "mobile_contracts": 1, "notifications": 3, "package_manifests": 4, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloFeed/topolo.app.json", "service_slug": "topolo-device-platform", "name": "TopoloFeed", "app_id": "app_topolo_feed", "compatibility_date": "2025-05-01", "primary_target": "web", "environments": [ "development", "production", "staging" ], "targets": [ { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-feed-web", "subdomain": "feed", "healthcheck_path": null, "variable_names": [ "AUTH_API_URL", "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "ANALYTICS", "target": null } ] }, { "name": "analytics", "kind": "worker", "directory": "apps/analytics", "main": "src/index.ts", "worker_name": "topolo-feed-analytics-api", "subdomain": "feed-analytics-api", "healthcheck_path": "/health", "variable_names": [ "AUTH_API_URL", "ENVIRONMENT", "FEED_PUBLIC_BASE_URL", "NEXUS_GATEWAY_URL", "RATE_LIMIT_ENABLED", "RATE_LIMIT_PERIOD", "RATE_LIMIT_REQUESTS", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "kv", "binding": "TOPOLO_FEED_CONFIG", "target": null }, { "kind": "kv", "binding": "TOPOLO_STATE", "target": null }, { "kind": "d1", "binding": "IMPRESSIONS_DB", "target": null }, { "kind": "d1", "binding": "DEVICES_DB", "target": null }, { "kind": "d1", "binding": "OPS_DB", "target": null }, { "kind": "d1", "binding": "REPORTING_DB", "target": null }, { "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 } ] }, { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/index.ts", "worker_name": "topolo-feed-api", "subdomain": "feed-api", "healthcheck_path": "/health", "variable_names": [ "AUTH_API_URL", "ENVIRONMENT", "NEXUS_GATEWAY_URL" ], "secret_names": [], "bindings": [ { "kind": "kv", "binding": "TOPOLO_FEED_CONFIG", "target": null }, { "kind": "kv", "binding": "TOPOLO_STATE", "target": null }, { "kind": "d1", "binding": "REPORTING_DB", "target": null }, { "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": [ "feed.digest.ready", "feed.engagement.anomaly_detected", "feed.source.sync_failed" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_feed", "events": [ { "type": "feed.digest.ready", "version": 1, "description": "A durable Feed engagement digest was generated for a workspace reporting window.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string" }, "dedupe_key": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "Feed digest is ready", "body": "Your Feed engagement digest has finished processing.", "object_id": "digest_123", "occurred_at": "2026-07-19T12:00:00.000Z", "payload": { "digest_id": "digest_123", "window_start": 1000, "window_end": 2000, "summary": [] } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^feed:digest:" }, "sensitiveFields": [] }, { "type": "feed.engagement.anomaly_detected", "version": 1, "description": "A durable workspace completion-rate check crossed its configured anomaly threshold.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string" }, "dedupe_key": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "Feed engagement needs attention", "body": "Completion rate fell to 42%.", "object_id": "anomaly_123", "occurred_at": "2026-07-19T12:00:00.000Z", "payload": { "anomaly_id": "anomaly_123", "metric": "completion_rate", "observed_value": 42, "threshold_value": 70, "window_start": 1000, "window_end": 2000 } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^feed:anomaly:" }, "sensitiveFields": [] }, { "type": "feed.source.sync_failed", "version": 1, "description": "A registered Feed content source reached a durable failed synchronization result.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string" }, "dedupe_key": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "Feed source sync failed: Partner catalog", "body": "Feed could not refresh this content source.", "object_id": "source_123", "occurred_at": "2026-07-19T12:00:00.000Z", "payload": { "source_id": "source_123", "sync_run_id": "sync_123", "reason": "source_http_503", "failed_at": "2026-07-19T12:00:00.000Z" } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^feed:source-sync:" }, "sensitiveFields": [] } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for Feed.", "method": "GET", "path": "/api/widget", "permission": "feed:read", "authorizationMode": "static", "readOnly": true, "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 }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-device-platform --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "analytics.summary.get", "title": "Get feed analytics summary", "description": "Summarize impressions for the active Feed workspace and optional time range.", "method": "GET", "path": "/api/analytics/summary", "permission": "analytics:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "start_time": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end_time": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ad_id_pattern": { "type": "string" } }, "additionalProperties": false }, "outputSchema": { "type": "object", "description": "Response returned by Get feed analytics summary.", "additionalProperties": true }, "target": "analytics", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example", "workspace_id": "00000000-0000-4000-8000-000000000000", "start_time": 1 }, "cli_example": [ "topolo actions --service topolo-device-platform --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/analytics/summary", "body": null }, "effects": "Reads state through GET /api/analytics/summary without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/analytics/summary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "analytics.engagement.get", "title": "Get feed engagement", "description": "Get completion, interaction, and duration metrics for the active Feed workspace.", "method": "GET", "path": "/api/analytics/engagement", "permission": "analytics:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "start_time": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end_time": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ad_id_pattern": { "type": "string" } }, "additionalProperties": false }, "outputSchema": { "type": "object", "description": "Response returned by Get feed engagement.", "additionalProperties": true }, "target": "analytics", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example", "workspace_id": "00000000-0000-4000-8000-000000000000", "start_time": 1 }, "cli_example": [ "topolo actions --service topolo-device-platform --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/analytics/engagement", "body": null }, "effects": "Reads state through GET /api/analytics/engagement without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/analytics/engagement", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "analytics.devices.list", "title": "List feed devices", "description": "List devices observed in the active Feed workspace.", "method": "GET", "path": "/api/analytics/devices", "permission": "analytics:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "outputSchema": { "type": "object", "description": "Response returned by List feed devices.", "additionalProperties": true }, "target": "analytics", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example", "workspace_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-device-platform --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/analytics/devices", "body": null }, "effects": "Reads state through GET /api/analytics/devices without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/analytics/devices", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "Delete feed workspace", "description": "Delete an empty non-default Feed workspace.", "method": "DELETE", "path": "/api/analytics/feed/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 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "description": "Response returned by Delete feed workspace.", "additionalProperties": true }, "target": "analytics", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-device-platform --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/analytics/feed/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/analytics/feed/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/analytics/feed/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "analytics.digest.generate", "title": "Generate feed digest", "description": "Persist an engagement digest for the active Feed workspace and emit its ready event.", "method": "POST", "path": "/api/analytics/digests", "permission": "feed:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "windowStart": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "windowEnd": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "windowStart", "windowEnd" ], "additionalProperties": false }, "outputSchema": { "type": "object", "description": "Response returned by Generate feed digest.", "additionalProperties": true }, "target": "analytics", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/applications/feed", "resource": { "kind": "feed_digest", "idPath": "$.digest.id" }, "effects": [ "Creates a workspace-scoped engagement digest and emits the feed.digest.ready notification event." ], "errors": [ { "status": 400, "code": "invalid_reporting_window", "recovery": "Choose a windowEnd greater than windowStart and retry." }, { "status": 403, "code": "forbidden", "recovery": "Use a credential with feed:write access to the selected Feed workspace." } ], "verify": [ "Confirm the response contains $.digest.id for the selected reporting window." ], "examples": [ { "input": { "windowStart": 1, "windowEnd": 2 }, "expected": "A persisted Feed engagement digest for the selected reporting window." } ] }, "documentation": { "example_input": { "windowStart": 1, "windowEnd": 2 }, "cli_example": [ "topolo actions --service topolo-device-platform --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/analytics/digests", "body": { "windowStart": 1, "windowEnd": 2 } }, "effects": "Creates a workspace-scoped engagement digest and emits the feed.digest.ready notification event.", "verification": [ "Confirm the response contains $.digest.id for the selected reporting window." ], "recovery": [ "400 invalid_reporting_window: Choose a windowEnd greater than windowStart and retry.", "403 forbidden: Use a credential with feed:write access to the selected Feed workspace." ], "docs_url": "https://docs.topolo.app/applications/feed", "resource": { "kind": "feed_digest", "idPath": "$.digest.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/analytics/digests", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "analytics.anomaly.check", "title": "Check feed engagement anomaly", "description": "Evaluate a completion-rate threshold and persist a detected workspace anomaly.", "method": "POST", "path": "/api/analytics/anomaly-checks", "permission": "feed:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "windowStart": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "windowEnd": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "minimumCompletionRate": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "windowStart", "windowEnd", "minimumCompletionRate" ], "additionalProperties": false }, "outputSchema": { "type": "object", "description": "Response returned by Check feed engagement anomaly.", "additionalProperties": true }, "target": "analytics", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/applications/feed", "resource": { "kind": "feed_engagement_anomaly", "idPath": "$.anomaly.id" }, "effects": [ "Evaluates the workspace completion rate and persists an anomaly when it is below minimumCompletionRate." ], "errors": [ { "status": 400, "code": "invalid_reporting_window", "recovery": "Choose a windowEnd greater than windowStart and retry." }, { "status": 403, "code": "forbidden", "recovery": "Use a credential with feed:write access to the selected Feed workspace." } ], "verify": [ "Confirm $.observedValue is present and, when below the threshold, $.anomaly.id identifies the persisted anomaly." ], "examples": [ { "input": { "windowStart": 1, "windowEnd": 2, "minimumCompletionRate": 75 }, "expected": "A Feed anomaly-check result for the selected reporting window and threshold." } ] }, "documentation": { "example_input": { "windowStart": 1, "windowEnd": 2, "minimumCompletionRate": 75 }, "cli_example": [ "topolo actions --service topolo-device-platform --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/analytics/anomaly-checks", "body": { "windowStart": 1, "windowEnd": 2, "minimumCompletionRate": 75 } }, "effects": "Evaluates the workspace completion rate and persists an anomaly when it is below minimumCompletionRate.", "verification": [ "Confirm $.observedValue is present and, when below the threshold, $.anomaly.id identifies the persisted anomaly." ], "recovery": [ "400 invalid_reporting_window: Choose a windowEnd greater than windowStart and retry.", "403 forbidden: Use a credential with feed:write access to the selected Feed workspace." ], "docs_url": "https://docs.topolo.app/applications/feed", "resource": { "kind": "feed_engagement_anomaly", "idPath": "$.anomaly.id" }, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/analytics/anomaly-checks", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "devices.credential.rotate", "title": "Rotate feed device credential", "description": "Issue a new one-time credential for a device in the active Feed workspace and invalidate its previous credential.", "method": "POST", "path": "/api/analytics/devices/{deviceId}/credential", "permission": "feed:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 } }, "required": [ "deviceId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "description": "Response returned by Rotate feed device credential.", "additionalProperties": true }, "target": "analytics", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "deviceId": "example" }, "cli_example": [ "topolo actions --service topolo-device-platform --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/analytics/devices/example/credential", "body": { "deviceId": "example" } }, "effects": "May change state through POST /api/analytics/devices/{deviceId}/credential. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/analytics/devices/*/credential", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sources.list", "title": "List feed sources", "description": "List registered content sources in the active Feed workspace.", "method": "GET", "path": "/api/analytics/sources", "permission": "feed:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "outputSchema": { "type": "object", "description": "Response returned by List feed sources.", "additionalProperties": true }, "target": "analytics", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example", "workspace_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-device-platform --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/analytics/sources", "body": null }, "effects": "Reads state through GET /api/analytics/sources without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/analytics/sources", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sources.create", "title": "Create feed source", "description": "Register an HTTPS content source in the active Feed workspace.", "method": "POST", "path": "/api/analytics/sources", "permission": "feed:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "endpointUrl": { "type": "string", "format": "uri", "pattern": "^https:\\/\\/.*" } }, "required": [ "name", "endpointUrl" ], "additionalProperties": false }, "outputSchema": { "type": "object", "description": "Response returned by Create feed source.", "additionalProperties": true }, "target": "analytics", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "name": "example", "endpointUrl": "https://example.com" }, "cli_example": [ "topolo actions --service topolo-device-platform --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/analytics/sources", "body": { "name": "example", "endpointUrl": "https://example.com" } }, "effects": "May change state through POST /api/analytics/sources. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/analytics/sources", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.export", "title": "Export Feed organization data", "description": "Export all Feed records for the authenticated organization with protected fields decrypted for the requester.", "method": "GET", "path": "/api/privacy", "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", "description": "Response returned by Export Feed organization data.", "additionalProperties": true }, "target": "analytics", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-device-platform --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/privacy", "body": null }, "effects": "Reads state through GET /api/privacy without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/privacy", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.delete", "title": "Erase Feed organization data", "description": "Permanently erase Feed records for the authenticated organization and retain only a hashed erasure receipt.", "method": "DELETE", "path": "/api/privacy", "permission": "workspace:delete", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false }, "outputSchema": { "type": "object", "description": "Response returned by Erase Feed organization data.", "additionalProperties": true }, "target": "analytics", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-device-platform --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/privacy", "body": null }, "effects": "May change state through DELETE /api/privacy. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/privacy", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.protection.canary", "title": "Check Feed data protection", "description": "Verify protected Feed D1 and KV fields decrypt and report any remaining plaintext records.", "method": "GET", "path": "/api/privacy/protection/canary", "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", "description": "Response returned by Check Feed data protection.", "additionalProperties": true }, "target": "analytics", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-device-platform --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/privacy/protection/canary", "body": null }, "effects": "Reads state through GET /api/privacy/protection/canary without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/privacy/protection/canary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sources.sync", "title": "Sync feed source", "description": "Refresh one registered Feed source and persist its terminal sync result.", "method": "POST", "path": "/api/analytics/sources/{sourceId}/sync", "permission": "feed:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sourceId": { "type": "string", "minLength": 1 } }, "required": [ "sourceId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "description": "Response returned by Sync feed source.", "additionalProperties": true }, "target": "analytics", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "sourceId": "example" }, "cli_example": [ "topolo actions --service topolo-device-platform --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/analytics/sources/example/sync", "body": { "sourceId": "example" } }, "effects": "May change state through POST /api/analytics/sources/{sourceId}/sync. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/analytics/sources/*/sync", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 20, "matched_actions": 14, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 6, "configured_exclusions": 3, "configuration_findings": [], "notes": [] }, "runtime_contract_audit": { "status": "verified", "actions": 14, "contracts": 14, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/analytics/src/index.ts", "apps/api/src/index.ts" ], "authorization_sources": [ "apps/analytics/src/index.ts", "apps/api/src/index.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloFeed/topolo.mobile-experience.json", "contract": { "version": "2026-07-03", "status": "approved", "mode": "native_capability", "appId": "app_topolo_feed", "localizationNamespace": "feed", "permissions": [ "feed:read" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/dashboard/devices", "auth": { "audience": "topolo-feed", "scopes": [ "feed:read" ], "orgContext": "required" }, "routes": [ { "path": "/dashboard/devices", "apiPath": "/api/widget", "title": "Devices", "titleKey": "feed.mobile.routes.devices.title", "template": "record.list", "dataSource": "feed.devices.list", "detailRoute": "/dashboard/media" }, { "path": "/dashboard/media", "apiPath": "/api/widget", "title": "Media feed", "titleKey": "feed.mobile.routes.media.title", "template": "record.detail", "dataSource": "feed.media.detail" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "DELETE", "path": "/analytics/feed/workspaces/:workspaceId", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "GET", "path": "/privacy", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "DELETE", "path": "/privacy", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "GET", "path": "/privacy/protection/canary", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "POST", "path": "/analytics", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "GET", "path": "/analytics/summary", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "GET", "path": "/analytics/engagement", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "GET", "path": "/analytics/devices", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "POST", "path": "/analytics/digests", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "POST", "path": "/analytics/anomaly-checks", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "POST", "path": "/analytics/devices/:deviceId/credential", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "POST", "path": "/analytics/sources", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "GET", "path": "/analytics/sources", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "POST", "path": "/analytics/sources/:sourceId/sync", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "GET", "path": "/health", "source_path": "apps/TopoloFeed/apps/analytics/src/index.ts" }, { "method": "GET", "path": "/health", "source_path": "apps/TopoloFeed/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/widget", "source_path": "apps/TopoloFeed/apps/api/src/index.ts" }, { "method": "GET", "path": "/", "source_path": "apps/TopoloFeed/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/:deviceId", "source_path": "apps/TopoloFeed/apps/api/src/index.ts" } ], "ui_routes": [ { "path": "/dashboard", "source_path": "apps/TopoloFeed/apps/web/src/App.tsx" }, { "path": "/dashboard/devices", "source_path": "apps/TopoloFeed/apps/web/src/App.tsx" }, { "path": "/dashboard/media", "source_path": "apps/TopoloFeed/apps/web/src/App.tsx" }, { "path": "/dashboard/getting-started", "source_path": "apps/TopoloFeed/apps/web/src/App.tsx" }, { "path": "/settings", "source_path": "apps/TopoloFeed/apps/web/src/App.tsx" }, { "path": "/settings/:section", "source_path": "apps/TopoloFeed/apps/web/src/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/device-platform", "internal/apps/device-platform", "applications/feed", "internal/apps/feed" ], "present_paths": [ "applications/device-platform", "internal/apps/device-platform", "applications/feed", "internal/apps/feed" ], "missing_paths": [], "human_reference": "/systems/topolo-device-platform", "machine_reference": "/machine/systems/topolo-device-platform.json", "action_examples": 14, "action_schemas": 14 }, "source_findings": [] }, "topolo-docs": { "id": "topolo-docs", "name": "TopoloDocs", "slug": "topolo-docs", "kind": "application", "visibility": "public", "repo_paths": [ "system-apps/TopoloDocs" ], "source_revisions": [ { "source_path": "system-apps/TopoloDocs", "repository": "system-apps/TopoloDocs", "revision": "content-sha256:f1156f3f8bfa67eea5ea769c2e21502bf7883b145bf30212f0ea11cc6a2b1140", "ref": "working-tree" } ], "source_counts": { "source_files": 98, "test_files": 70, "test_cases": 0, "migration_files": 7, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 34, "mobile_contracts": 0, "notifications": 4, "package_manifests": 3, "deployment_configs": 0 }, "manifests": [ { "source_path": "system-apps/TopoloDocs/topolo.app.json", "service_slug": "topolo-docs", "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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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-docs --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": [] } } ], "mobile_contracts": [], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "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" } ], "ui_routes": [ { "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": [ "applications/docs", "internal/apps/docs" ], "present_paths": [ "applications/docs", "internal/apps/docs" ], "missing_paths": [], "human_reference": "/systems/topolo-docs", "machine_reference": "/machine/systems/topolo-docs.json", "action_examples": 34, "action_schemas": 34 }, "source_findings": [] }, "topolo-forecast": { "id": "topolo-forecast", "name": "Topolo Forecast", "slug": "topolo-forecast", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloForecast" ], "source_revisions": [ { "source_path": "apps/TopoloForecast", "repository": "apps/TopoloForecast", "revision": "e1e2cb0fb630c8da1d3fc157c568b6ec072ccc7a", "ref": "origin/staging" } ], "source_counts": { "source_files": 188, "test_files": 91, "test_cases": 0, "migration_files": 0, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 52, "mobile_contracts": 1, "notifications": 6, "package_manifests": 6, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloForecast/topolo.app.json", "service_slug": "topolo-forecast", "name": "topolo-forecast", "app_id": "app_topolo_forecast", "compatibility_date": "2026-04-10", "primary_target": null, "environments": [ "development", "production", "staging" ], "targets": [ { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-forecast", "subdomain": "forecast", "healthcheck_path": null, "variable_names": [ "AUTH_API_URL", "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null } ] }, { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/index.ts", "worker_name": "topolo-forecast-api", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "APP_ID", "AUTH_BASE_URL", "ENVIRONMENT", "FORECAST_PUBLIC_BASE_URL", "NEXUS_GATEWAY_URL", "SERVICE_NAME", "SERVICE_SLUG", "TOPOLO_NOTIFY_URL", "TOPOLO_SEED_APP_ID" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "FORECAST_CONTROL_DB", "target": null }, { "kind": "d1", "binding": "FORECAST_PLAN_DB", "target": null }, { "kind": "d1", "binding": "FORECAST_CASH_DB", "target": null }, { "kind": "d1", "binding": "FORECAST_ACCESS_DB", "target": null }, { "kind": "d1", "binding": "FORECAST_AUDIT_DB", "target": null }, { "kind": "kv", "binding": "FS_CACHE", "target": null }, { "kind": "durableObjects", "binding": "CACHE_STORE", "target": null } ] } ], "notifications": [ "forecast.cash_threshold_breached", "forecast.import.completed", "forecast.import.failed", "forecast.scenario.ready", "forecast.schedule_rule.due", "forecast.share.invited" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_forecast", "events": [ { "type": "forecast.cash_threshold_breached", "version": 1, "description": "Forecast durably recorded a transition below a configured cash threshold.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "balance_cents", "threshold_cents", "severity", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "balance_cents": { "type": "integer" }, "threshold_cents": { "type": "integer" }, "severity": { "type": "string", "enum": [ "low", "critical" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Critical cash threshold breached", "body": "Available cash is $500.00 against the $1,000.00 threshold.", "object_id": "workspace_1", "balance_cents": 50000, "threshold_cents": 100000, "severity": "critical", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://forecast.topolo.app/cash" } ], "dataClassification": "confidential", "sensitiveFields": [ "balance_cents", "threshold_cents" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^forecast:cash-threshold:" } }, { "type": "forecast.import.completed", "version": 1, "description": "A bounded forecast import and its terminal completed job were committed atomically.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "import_id", "scenario_id", "status", "row_count", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "import_id": { "type": "string", "minLength": 1 }, "scenario_id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "const": "completed" }, "row_count": { "type": "integer", "minimum": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Forecast import completed", "body": "24 forecast rows were imported.", "object_id": "forecast_import_1", "import_id": "forecast_import_1", "scenario_id": "scenario_1", "status": "completed", "row_count": 24, "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://forecast.topolo.app/imports/forecast_import_1" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^forecast:import-completed:" } }, { "type": "forecast.import.failed", "version": 1, "description": "A rejected forecast import was persisted as a terminal failed job.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "import_id", "scenario_id", "status", "row_count", "error", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "import_id": { "type": "string", "minLength": 1 }, "scenario_id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "const": "failed" }, "row_count": { "type": "integer", "const": 0 }, "error": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Forecast import failed", "body": "Import must contain between 1 and 500 entries.", "object_id": "forecast_import_2", "import_id": "forecast_import_2", "scenario_id": "scenario_1", "status": "failed", "row_count": 0, "error": "Import must contain between 1 and 500 entries.", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://forecast.topolo.app/imports/forecast_import_2" } ], "dataClassification": "internal", "sensitiveFields": [ "error" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^forecast:import-failed:" } }, { "type": "forecast.scenario.ready", "version": 1, "description": "A new forecast scenario and its ready notification were committed atomically.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "scenario_id", "scenario_name", "base_scenario_id", "status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "scenario_id": { "type": "string", "minLength": 1 }, "scenario_name": { "type": "string", "minLength": 1 }, "base_scenario_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "const": "ready" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Forecast scenario is ready", "body": "FY27 plan is ready for planning.", "object_id": "scenario_1", "scenario_id": "scenario_1", "scenario_name": "FY27 plan", "base_scenario_id": null, "status": "ready", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://forecast.topolo.app/scenarios/scenario_1" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^forecast:scenario-ready:" } }, { "type": "forecast.schedule_rule.due", "version": 1, "description": "A due schedule-rule delivery was claimed once and persisted with its notification.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "rule_id", "rule_name", "scenario_id", "coa_id", "amount_cents", "due_date", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "rule_id": { "type": "string", "minLength": 1 }, "rule_name": { "type": [ "string", "null" ] }, "scenario_id": { "type": "string", "minLength": 1 }, "coa_id": { "type": "string", "minLength": 1 }, "amount_cents": { "type": "integer" }, "due_date": { "type": "string", "format": "date" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Forecast schedule rule is due", "body": "Monthly payroll is due today.", "object_id": "rule_1", "rule_id": "rule_1", "rule_name": "Monthly payroll", "scenario_id": "scenario_1", "coa_id": "coa_payroll", "amount_cents": -2500000, "due_date": "2026-07-20", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://forecast.topolo.app/schedule-rules" } ], "dataClassification": "confidential", "sensitiveFields": [ "amount_cents" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^forecast:schedule-rule-due:" } }, { "type": "forecast.share.invited", "version": 1, "description": "A workspace member was durably attached to a newly created Forecast share.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "share_id", "share_name", "invited_by_user_id", "permission_level", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "share_id": { "type": "string", "minLength": 1 }, "share_name": { "type": "string", "minLength": 1 }, "invited_by_user_id": { "type": "string", "minLength": 1 }, "permission_level": { "type": "string", "enum": [ "read", "collaborate" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Forecast share invitation", "body": "Alex invited you to Board pack.", "object_id": "share_1", "share_id": "share_1", "share_name": "Board pack", "invited_by_user_id": "user_alex", "permission_level": "read", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://forecast.topolo.app/shared/token" } ], "dataClassification": "confidential", "sensitiveFields": [ "cta_url" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^forecast:share-invited:" } } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "dashboard: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-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "coa.get", "title": "Get chart of accounts", "description": "Get Forecast chart of accounts.", "method": "GET", "path": "/api/v1/{workspace}/coa", "permission": "forecasts:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 } }, "required": [ "workspace" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get chart of accounts.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/coa", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/coa without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/coa", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.set_active_scenario", "title": "Set active scenario", "description": "Set the active Forecast workspace scenario.", "method": "PATCH", "path": "/api/v1/workspaces/{id}/active-scenario", "permission": "workspace:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "scenarioId": { "type": "string", "minLength": 1 } }, "required": [ "id", "scenarioId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Set active scenario.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "scenarioId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/v1/workspaces/00000000-0000-4000-8000-000000000000/active-scenario", "body": { "id": "00000000-0000-4000-8000-000000000000", "scenarioId": "example" } }, "effects": "May change state through PATCH /api/v1/workspaces/{id}/active-scenario. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/v1/workspaces/*/active-scenario", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "Delete workspace", "description": "Delete a Forecast workspace.", "method": "DELETE", "path": "/api/v1/workspaces/{id}", "permission": "workspace:delete", "authorizationMode": "static", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete workspace.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/v1/workspaces/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/v1/workspaces/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/v1/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspace_shares.list", "title": "List workspace shares", "description": "List Forecast workspace shares.", "method": "GET", "path": "/api/v1/workspaces/{workspaceId}/shares", "permission": "forecasts:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List workspace shares.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/workspaces/example/shares", "body": null }, "effects": "Reads state through GET /api/v1/workspaces/{workspaceId}/shares without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/workspaces/*/shares", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspace_shares.create", "title": "Create workspace share", "description": "Create a Forecast workspace share.", "method": "POST", "path": "/api/v1/workspaces/{workspaceId}/shares", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "permission_level": { "type": "string", "enum": [ "read", "collaborate" ] }, "expires_at": { "type": "string", "minLength": 1 }, "max_accesses": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "recipient_user_id": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId", "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create workspace share.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example", "name": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/v1/workspaces/example/shares", "body": { "workspaceId": "example", "name": "example" } }, "effects": "May change state through POST /api/v1/workspaces/{workspaceId}/shares. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/v1/workspaces/*/shares", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspace_shares.update", "title": "Update workspace share", "description": "Update a Forecast workspace share.", "method": "PATCH", "path": "/api/v1/workspaces/{workspaceId}/shares/{shareId}", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "shareId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "permission_level": { "type": "string", "enum": [ "read", "collaborate" ] }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "minLength": 1 }, "max_accesses": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "workspaceId", "shareId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update workspace share.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example", "shareId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/v1/workspaces/example/shares/example", "body": { "workspaceId": "example", "shareId": "example" } }, "effects": "May change state through PATCH /api/v1/workspaces/{workspaceId}/shares/{shareId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/v1/workspaces/*/shares/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspace_shares.delete", "title": "Delete workspace share", "description": "Delete a Forecast workspace share.", "method": "DELETE", "path": "/api/v1/workspaces/{workspaceId}/shares/{shareId}", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "shareId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId", "shareId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete workspace share.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example", "shareId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/v1/workspaces/example/shares/example", "body": null }, "effects": "May change state through DELETE /api/v1/workspaces/{workspaceId}/shares/{shareId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/v1/workspaces/*/shares/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "share_settings.get", "title": "Get share settings", "description": "Get Forecast workspace share settings.", "method": "GET", "path": "/api/v1/workspaces/{workspaceId}/share-settings", "permission": "settings:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get share settings.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/workspaces/example/share-settings", "body": null }, "effects": "Reads state through GET /api/v1/workspaces/{workspaceId}/share-settings without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/workspaces/*/share-settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "share_settings.update", "title": "Update share settings", "description": "Update Forecast workspace share settings.", "method": "PATCH", "path": "/api/v1/workspaces/{workspaceId}/share-settings", "permission": "settings:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "sharing_enabled": { "type": "boolean" }, "default_permission_level": { "type": "string", "enum": [ "read", "collaborate" ] }, "default_expiry_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_active_shares": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "require_password": { "type": "boolean" }, "allowed_domains": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "custom_branding_enabled": { "type": "boolean" }, "custom_logo_url": { "type": "string", "minLength": 1 }, "custom_title": { "type": "string", "minLength": 1 }, "custom_description": { "type": "string", "minLength": 1 }, "analytics_enabled": { "type": "boolean" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update share settings.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/v1/workspaces/example/share-settings", "body": { "workspaceId": "example" } }, "effects": "May change state through PATCH /api/v1/workspaces/{workspaceId}/share-settings. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/v1/workspaces/*/share-settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "scenarios.list", "title": "List scenarios", "description": "List Forecast scenarios.", "method": "GET", "path": "/api/v1/{workspace}/scenarios", "permission": "forecasts:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 } }, "required": [ "workspace" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List scenarios.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/scenarios", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/scenarios without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/scenarios", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "scenarios.create", "title": "Create scenario", "description": "Create a Forecast scenario in a platform-authorized workspace, including the first scenario for a newly created workspace.", "method": "POST", "path": "/api/v1/{workspace}/scenarios", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "base_scenario_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "workspace", "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Created Forecast scenario.", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "workspace_id" ], "additionalProperties": true }, "message": { "type": "string" } }, "required": [ "success", "data" ], "additionalProperties": true }, "agentContract": { "docsUrl": "https://docs.topolo.app/applications/forecast", "resource": { "kind": "scenario", "idPath": "$.data.id" }, "effects": [ "Creates a planning scenario in the selected platform-authorized Forecast workspace. This is the bootstrap action for a newly created workspace." ], "errors": [ { "status": 403, "code": "action_permission_required", "recovery": "Use a credential with forecasts:write access to the selected Forecast workspace." } ], "verify": [ "Call scenarios.list with the same workspace and confirm the returned list contains $.data.id and the requested name." ], "nextActionIds": [ "app_topolo_forecast.scenarios.list", "app_topolo_forecast.coa.create", "app_topolo_forecast.cash_accounts.create" ], "examples": [ { "title": "Create the base operating plan", "input": { "workspace": "ws_forecast_northstar", "name": "Northstar FY27 Base Plan" } } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_forecast.scenarios.delete", "requiresSnapshot": false, "instructions": "Archive the created scenario only after confirming no dependent planning data should be retained." } }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "ws_forecast_northstar", "name": "Northstar FY27 Base Plan" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/v1/ws_forecast_northstar/scenarios", "body": { "workspace": "ws_forecast_northstar", "name": "Northstar FY27 Base Plan" } }, "effects": "Creates a planning scenario in the selected platform-authorized Forecast workspace. This is the bootstrap action for a newly created workspace.", "verification": [ "Call scenarios.list with the same workspace and confirm the returned list contains $.data.id and the requested name." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_forecast.scenarios.delete", "requiresSnapshot": false, "instructions": "Archive the created scenario only after confirming no dependent planning data should be retained." }, "403 action_permission_required: Use a credential with forecasts:write access to the selected Forecast workspace." ], "docs_url": "https://docs.topolo.app/applications/forecast", "resource": { "kind": "scenario", "idPath": "$.data.id" }, "next_action_ids": [ "app_topolo_forecast.scenarios.list", "app_topolo_forecast.coa.create", "app_topolo_forecast.cash_accounts.create" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/v1/*/scenarios", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "scenarios.update", "title": "Update scenario", "description": "Update a Forecast scenario.", "method": "PATCH", "path": "/api/v1/{workspace}/scenarios/{scenarioId}", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "scenarioId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "archived": { "type": "boolean" } }, "required": [ "workspace", "scenarioId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update scenario.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "scenarioId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/v1/example/scenarios/example", "body": { "workspace": "example", "scenarioId": "example" } }, "effects": "May change state through PATCH /api/v1/{workspace}/scenarios/{scenarioId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/v1/*/scenarios/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "scenarios.duplicate", "title": "Duplicate scenario", "description": "Duplicate a Forecast scenario.", "method": "POST", "path": "/api/v1/{workspace}/scenarios/{scenarioId}/duplicate", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "scenarioId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "scenarioId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Duplicate scenario.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "scenarioId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/v1/example/scenarios/example/duplicate", "body": { "workspace": "example", "scenarioId": "example" } }, "effects": "May change state through POST /api/v1/{workspace}/scenarios/{scenarioId}/duplicate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/v1/*/scenarios/*/duplicate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "scenarios.delete", "title": "Delete scenario", "description": "Delete a Forecast scenario.", "method": "DELETE", "path": "/api/v1/{workspace}/scenarios/{scenarioId}", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "scenarioId": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "scenarioId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete scenario.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "scenarioId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/v1/example/scenarios/example", "body": null }, "effects": "May change state through DELETE /api/v1/{workspace}/scenarios/{scenarioId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/v1/*/scenarios/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "coa.create", "title": "Create chart account", "description": "Create a Forecast chart of accounts entry.", "method": "POST", "path": "/api/v1/{workspace}/coa", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "income", "cos", "opex", "calc" ] }, "trend_factor": { "type": "number" }, "parentId": { "type": "string", "minLength": 1 }, "order_index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "workspace", "name", "type" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create chart account.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "name": "example", "type": "income" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/v1/example/coa", "body": { "workspace": "example", "name": "example", "type": "income" } }, "effects": "May change state through POST /api/v1/{workspace}/coa. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/v1/*/coa", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "coa.update", "title": "Update chart account", "description": "Update a Forecast chart of accounts entry.", "method": "PATCH", "path": "/api/v1/{workspace}/coa/{id}", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "income", "cos", "opex", "calc" ] }, "trend_factor": { "type": "number", "minimum": -10, "maximum": 10 }, "parentId": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update chart account.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/v1/example/coa/00000000-0000-4000-8000-000000000000", "body": { "workspace": "example", "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PATCH /api/v1/{workspace}/coa/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/v1/*/coa/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "coa.delete", "title": "Delete chart account", "description": "Delete a Forecast chart of accounts entry.", "method": "DELETE", "path": "/api/v1/{workspace}/coa/{id}", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 }, "force": { "type": "boolean" } }, "required": [ "workspace", "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete chart account.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/v1/example/coa/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/v1/{workspace}/coa/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/v1/*/coa/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "daily.get", "title": "Get daily entries", "description": "Get Forecast daily entries for a period.", "method": "GET", "path": "/api/v1/{workspace}/daily/{period}", "permission": "transactions:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "period": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } }, "required": [ "workspace", "period" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get daily entries.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example", "period": "2026-01" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/daily/2026-01", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/daily/{period} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/daily/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "daily.annual.get", "title": "Get annual daily entries", "description": "Get Forecast daily entries for a year.", "method": "GET", "path": "/api/v1/{workspace}/daily/annual/{year}", "permission": "transactions:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "year": { "type": "string", "pattern": "^\\d{4}$" } }, "required": [ "workspace", "year" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get annual daily entries.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example", "year": "2026" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/daily/annual/2026", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/daily/annual/{year} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/daily/annual/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "daily.upsert", "title": "Upsert daily entry", "description": "Upsert a Forecast daily entry.", "method": "PUT", "path": "/api/v1/{workspace}/daily", "permission": "transactions:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "coaId": { "type": "string", "minLength": 1 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amountCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isActual": { "type": "boolean" }, "note": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "coaId", "date", "amountCents" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Upsert daily entry.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "coaId": "example", "date": "2026-01-01", "amountCents": 1 }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/v1/example/daily", "body": { "workspace": "example", "coaId": "example", "date": "2026-01-01", "amountCents": 1 } }, "effects": "May change state through PUT /api/v1/{workspace}/daily. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/v1/*/daily", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "daily.bulk_upsert", "title": "Bulk upsert daily entries", "description": "Bulk upsert Forecast daily entries.", "method": "PUT", "path": "/api/v1/{workspace}/daily/bulk", "permission": "transactions:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "entries": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "coaId": { "type": "string", "minLength": 1 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amountCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isActual": { "type": "boolean" }, "note": { "type": "string", "minLength": 1 } }, "required": [ "coaId", "date", "amountCents" ], "additionalProperties": false } } }, "required": [ "workspace", "entries" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Bulk upsert daily entries.", "additionalProperties": true }, "agentContract": { "docsUrl": "https://docs.topolo.app/applications/forecast", "resource": { "kind": "daily_entry_batch", "idPath": "data" }, "effects": [ "Creates or replaces up to 100 Forecast daily entries in the workspace's active scenario, keyed by chart-of-account id and date." ], "errors": [ { "status": 500, "code": "BULK_DAILY_ENTRY_SAVE_ERROR", "recovery": "Preserve the submitted entries and request id, then retry only after the Forecast service reports healthy; entries already written remain upsert-safe by workspace, scenario, chart-of-account id, and date." } ], "verify": [ "Call daily.annual.get for every affected year in the same workspace and compare each submitted chart-of-account id, date, amountCents, isActual, and note." ], "nextActionIds": [ "app_topolo_forecast.daily.annual.get" ], "examples": [ { "title": "Upsert one monthly planning entry", "input": { "workspace": "operating-plan", "entries": [ { "coaId": "account-revenue", "date": "2026-10-01", "amountCents": 6500000, "isActual": false, "note": "Base-case monthly forecast" } ] } } ] }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "operating-plan", "entries": [ { "coaId": "account-revenue", "date": "2026-10-01", "amountCents": 6500000, "isActual": false, "note": "Base-case monthly forecast" } ] }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/v1/operating-plan/daily/bulk", "body": { "workspace": "operating-plan", "entries": [ { "coaId": "account-revenue", "date": "2026-10-01", "amountCents": 6500000, "isActual": false, "note": "Base-case monthly forecast" } ] } }, "effects": "Creates or replaces up to 100 Forecast daily entries in the workspace's active scenario, keyed by chart-of-account id and date.", "verification": [ "Call daily.annual.get for every affected year in the same workspace and compare each submitted chart-of-account id, date, amountCents, isActual, and note." ], "recovery": [ "500 BULK_DAILY_ENTRY_SAVE_ERROR: Preserve the submitted entries and request id, then retry only after the Forecast service reports healthy; entries already written remain upsert-safe by workspace, scenario, chart-of-account id, and date." ], "docs_url": "https://docs.topolo.app/applications/forecast", "resource": { "kind": "daily_entry_batch", "idPath": "data" }, "next_action_ids": [ "app_topolo_forecast.daily.annual.get" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/v1/*/daily/bulk", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "imports.run", "title": "Import forecast entries", "description": "Persist a bounded batch of Forecast entries and its terminal import result.", "method": "POST", "path": "/api/v1/{workspace}/imports", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "entries": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "coaId": { "type": "string", "minLength": 1 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amountCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isActual": { "type": "boolean" }, "note": { "type": "string", "minLength": 1 } }, "required": [ "coaId", "date", "amountCents" ], "additionalProperties": false } } }, "required": [ "workspace", "entries" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Import forecast entries.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "entries": [ { "coaId": "example", "date": "2026-01-01", "amountCents": 1 } ] }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/v1/example/imports", "body": { "workspace": "example", "entries": [ { "coaId": "example", "date": "2026-01-01", "amountCents": 1 } ] } }, "effects": "May change state through POST /api/v1/{workspace}/imports. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/v1/*/imports", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "summary.month.get", "title": "Get monthly summary", "description": "Get Forecast monthly summary.", "method": "GET", "path": "/api/v1/{workspace}/summary/month/{period}", "permission": "reports:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "period": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } }, "required": [ "workspace", "period" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get monthly summary.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example", "period": "2026-01" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/summary/month/2026-01", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/summary/month/{period} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/summary/month/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "summary.year.get", "title": "Get yearly summary", "description": "Get Forecast yearly summary.", "method": "GET", "path": "/api/v1/{workspace}/summary/year/{period}", "permission": "reports:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "period": { "type": "string", "pattern": "^\\d{4}$" } }, "required": [ "workspace", "period" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get yearly summary.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example", "period": "2026" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/summary/year/2026", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/summary/year/{period} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/summary/year/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "forecast.get", "title": "Get forecast", "description": "Get Forecast projection for a period.", "method": "GET", "path": "/api/v1/{workspace}/forecast/{period}", "permission": "forecasts:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "period": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "depth": { "type": "integer", "minimum": 1, "maximum": 36 } }, "required": [ "workspace", "period" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get forecast.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example", "period": "2026-01" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/forecast/2026-01", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/forecast/{period} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/forecast/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "openclaw.events.list", "title": "List OpenClaw events", "description": "List Forecast OpenClaw events.", "method": "GET", "path": "/api/v1/{workspace}/openclaw/events", "permission": "reports:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "since": { "type": "string", "minLength": 1 }, "scenarioId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "workspace" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List OpenClaw events.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/openclaw/events", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/openclaw/events without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/openclaw/events", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "openclaw.forecast_health.get", "title": "Get forecast health", "description": "Get Forecast OpenClaw health.", "method": "GET", "path": "/api/v1/{workspace}/openclaw/forecast-health", "permission": "reports:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "period": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "depth": { "type": "integer", "minimum": 1, "maximum": 36 }, "stale_after_hours": { "type": "integer", "minimum": 1, "maximum": 720 } }, "required": [ "workspace" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get forecast health.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/openclaw/forecast-health", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/openclaw/forecast-health without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/openclaw/forecast-health", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "openclaw.report_status.create", "title": "Create report status", "description": "Create Forecast OpenClaw report status.", "method": "POST", "path": "/api/v1/{workspace}/openclaw/report-status", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "stale" ] }, "runId": { "type": "string", "minLength": 1 }, "scenarioId": { "type": "string", "minLength": 1 }, "period": { "type": "string", "minLength": 1 }, "format": { "type": "string", "minLength": 1 }, "scheduledFor": { "type": "string", "minLength": 1 }, "startedAt": { "type": "string", "minLength": 1 }, "completedAt": { "type": "string", "minLength": 1 }, "artifactUrl": { "type": "string", "minLength": 1 }, "error": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "workspace", "name", "status" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create report status.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "name": "example", "status": "queued" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/v1/example/openclaw/report-status", "body": { "workspace": "example", "name": "example", "status": "queued" } }, "effects": "May change state through POST /api/v1/{workspace}/openclaw/report-status. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/v1/*/openclaw/report-status", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "openclaw.export_status.create", "title": "Create export status", "description": "Create Forecast OpenClaw export status.", "method": "POST", "path": "/api/v1/{workspace}/openclaw/export-status", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "stale" ] }, "runId": { "type": "string", "minLength": 1 }, "scenarioId": { "type": "string", "minLength": 1 }, "period": { "type": "string", "minLength": 1 }, "format": { "type": "string", "minLength": 1 }, "scheduledFor": { "type": "string", "minLength": 1 }, "startedAt": { "type": "string", "minLength": 1 }, "completedAt": { "type": "string", "minLength": 1 }, "artifactUrl": { "type": "string", "minLength": 1 }, "error": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "workspace", "name", "status" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create export status.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "name": "example", "status": "queued" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/v1/example/openclaw/export-status", "body": { "workspace": "example", "name": "example", "status": "queued" } }, "effects": "May change state through POST /api/v1/{workspace}/openclaw/export-status. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/v1/*/openclaw/export-status", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "cash_accounts.list", "title": "List cash accounts", "description": "List Forecast cash accounts.", "method": "GET", "path": "/api/v1/{workspace}/cash-accounts", "permission": "settings:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 } }, "required": [ "workspace" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List cash accounts.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/cash-accounts", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/cash-accounts without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/cash-accounts", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "cash_accounts.create", "title": "Create cash account", "description": "Create a workspace-level Forecast cash account. A scenario is not required.", "method": "POST", "path": "/api/v1/{workspace}/cash-accounts", "permission": "settings:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "account_name": { "type": "string", "minLength": 1 }, "account_type": { "type": "string", "enum": [ "checking", "savings", "investment", "cash", "credit_card", "other" ] }, "starting_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "display_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "workspace", "account_name", "account_type" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Created Forecast cash account.", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "account_name": { "type": "string", "minLength": 1 }, "account_type": { "type": "string" } }, "required": [ "id", "workspace_id", "account_name", "account_type" ], "additionalProperties": true } }, "required": [ "success", "data" ], "additionalProperties": true }, "agentContract": { "docsUrl": "https://docs.topolo.app/applications/forecast", "resource": { "kind": "cash_account", "idPath": "$.data.id" }, "effects": [ "Creates a workspace-level cash account and initializes its current balance from starting_balance_cents." ], "errors": [ { "status": 403, "code": "action_permission_required", "recovery": "Use a credential with settings:write access to the selected Forecast workspace." } ], "verify": [ "Call cash_accounts.list with the same workspace and confirm the returned list contains $.data.id, account_name, account_type, and starting balance." ], "nextActionIds": [ "app_topolo_forecast.cash_accounts.list" ], "examples": [ { "title": "Create an operating account", "input": { "workspace": "ws_forecast_northstar", "account_name": "Northstar Operating Account", "account_type": "checking", "starting_balance_cents": 1850000, "display_order": 1 } } ], "recovery": { "mode": "compensating_action", "actionId": "app_topolo_forecast.cash_accounts.delete", "requiresSnapshot": false, "instructions": "Delete the created account only after confirming it has no cash-flow entries that must be retained." } }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "ws_forecast_northstar", "account_name": "Northstar Operating Account", "account_type": "checking", "starting_balance_cents": 1850000, "display_order": 1 }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/v1/ws_forecast_northstar/cash-accounts", "body": { "workspace": "ws_forecast_northstar", "account_name": "Northstar Operating Account", "account_type": "checking", "starting_balance_cents": 1850000, "display_order": 1 } }, "effects": "Creates a workspace-level cash account and initializes its current balance from starting_balance_cents.", "verification": [ "Call cash_accounts.list with the same workspace and confirm the returned list contains $.data.id, account_name, account_type, and starting balance." ], "recovery": [ { "mode": "compensating_action", "actionId": "app_topolo_forecast.cash_accounts.delete", "requiresSnapshot": false, "instructions": "Delete the created account only after confirming it has no cash-flow entries that must be retained." }, "403 action_permission_required: Use a credential with settings:write access to the selected Forecast workspace." ], "docs_url": "https://docs.topolo.app/applications/forecast", "resource": { "kind": "cash_account", "idPath": "$.data.id" }, "next_action_ids": [ "app_topolo_forecast.cash_accounts.list" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/v1/*/cash-accounts", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "cash_accounts.update", "title": "Update cash account", "description": "Update a Forecast cash account.", "method": "PATCH", "path": "/api/v1/{workspace}/cash-accounts/{accountId}", "permission": "settings:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "accountId": { "type": "string", "minLength": 1 }, "account_name": { "type": "string", "minLength": 1 }, "account_type": { "type": "string", "enum": [ "checking", "savings", "investment", "cash", "credit_card", "other" ] }, "starting_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "current_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "is_active": { "type": "boolean" }, "display_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "workspace", "accountId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update cash account.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "accountId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/v1/example/cash-accounts/example", "body": { "workspace": "example", "accountId": "example" } }, "effects": "May change state through PATCH /api/v1/{workspace}/cash-accounts/{accountId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/v1/*/cash-accounts/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "cash_accounts.delete", "title": "Delete cash account", "description": "Delete a Forecast cash account.", "method": "DELETE", "path": "/api/v1/{workspace}/cash-accounts/{accountId}", "permission": "settings:write", "authorizationMode": "static", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "accountId": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "accountId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete cash account.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "accountId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/v1/example/cash-accounts/example", "body": null }, "effects": "May change state through DELETE /api/v1/{workspace}/cash-accounts/{accountId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/v1/*/cash-accounts/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "cash_flow.get", "title": "Get cash flow", "description": "Get Forecast cash flow for a period.", "method": "GET", "path": "/api/v1/{workspace}/cash-flow/{period}", "permission": "transactions:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "period": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } }, "required": [ "workspace", "period" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get cash flow.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example", "period": "2026-01" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/cash-flow/2026-01", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/cash-flow/{period} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/cash-flow/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "cash_flow.create", "title": "Create cash flow entry", "description": "Create a Forecast cash flow entry.", "method": "POST", "path": "/api/v1/{workspace}/cash-flow", "permission": "transactions:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "cash_account_id": { "type": "string", "minLength": 1 }, "entry_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": { "type": "string", "minLength": 1 }, "category": { "type": "string", "enum": [ "revenue", "expense", "transfer", "adjustment", "starting_balance" ] }, "p_and_l_account_id": { "type": "string", "minLength": 1 }, "transfer_account_id": { "type": "string", "minLength": 1 }, "transfer_group_id": { "type": "string", "minLength": 1 }, "is_actual": { "type": "boolean" } }, "required": [ "workspace", "cash_account_id", "entry_date", "amount_cents", "category" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create cash flow entry.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "cash_account_id": "00000000-0000-4000-8000-000000000000", "entry_date": "2026-01-01", "amount_cents": 1, "category": "revenue" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/v1/example/cash-flow", "body": { "workspace": "example", "cash_account_id": "00000000-0000-4000-8000-000000000000", "entry_date": "2026-01-01", "amount_cents": 1, "category": "revenue" } }, "effects": "May change state through POST /api/v1/{workspace}/cash-flow. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/v1/*/cash-flow", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "cash_flow.update", "title": "Update cash flow entry", "description": "Update a Forecast cash flow entry.", "method": "PATCH", "path": "/api/v1/{workspace}/cash-flow/{entryId}", "permission": "transactions:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "entryId": { "type": "string", "minLength": 1 }, "entry_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": { "type": "string", "minLength": 1 }, "category": { "type": "string", "enum": [ "revenue", "expense", "transfer", "adjustment", "starting_balance" ] }, "p_and_l_account_id": { "type": "string", "minLength": 1 }, "transfer_account_id": { "type": "string", "minLength": 1 }, "transfer_group_id": { "type": "string", "minLength": 1 }, "is_actual": { "type": "boolean" } }, "required": [ "workspace", "entryId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update cash flow entry.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "entryId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/v1/example/cash-flow/example", "body": { "workspace": "example", "entryId": "example" } }, "effects": "May change state through PATCH /api/v1/{workspace}/cash-flow/{entryId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/v1/*/cash-flow/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "cash_flow.delete", "title": "Delete cash flow entry", "description": "Delete a Forecast cash flow entry.", "method": "DELETE", "path": "/api/v1/{workspace}/cash-flow/{entryId}", "permission": "transactions:write", "authorizationMode": "static", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "entryId": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "entryId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete cash flow entry.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "entryId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/v1/example/cash-flow/example", "body": null }, "effects": "May change state through DELETE /api/v1/{workspace}/cash-flow/{entryId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/v1/*/cash-flow/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "cash_settings.get", "title": "Get cash settings", "description": "Get Forecast cash settings.", "method": "GET", "path": "/api/v1/{workspace}/cash-settings", "permission": "settings:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 } }, "required": [ "workspace" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get cash settings.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/cash-settings", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/cash-settings without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/cash-settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "cash_settings.update", "title": "Update cash settings", "description": "Update Forecast cash settings.", "method": "PATCH", "path": "/api/v1/{workspace}/cash-settings", "permission": "settings:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "low_cash_warning_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "critical_cash_warning_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "auto_generate_forecasts": { "type": "boolean" }, "workspace_profile": { "type": "string", "enum": [ "business", "personal" ] } }, "required": [ "workspace" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update cash settings.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/v1/example/cash-settings", "body": { "workspace": "example" } }, "effects": "May change state through PATCH /api/v1/{workspace}/cash-settings. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/v1/*/cash-settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "schedule_rules.list", "title": "List schedule rules", "description": "List Forecast schedule rules.", "method": "GET", "path": "/api/v1/{workspace}/schedule-rules", "permission": "settings:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "scenario_id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 } }, "required": [ "workspace" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List schedule rules.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/schedule-rules", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/schedule-rules without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/schedule-rules", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "schedule_rules.create", "title": "Create schedule rule", "description": "Create a Forecast schedule rule.", "method": "POST", "path": "/api/v1/{workspace}/schedule-rules", "permission": "settings:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "scenario_id": { "type": "string", "minLength": 1 }, "coa_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pattern_type": { "type": "string", "minLength": 1 }, "pattern_config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "is_active": { "type": "boolean" } }, "required": [ "workspace" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create schedule rule.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/v1/example/schedule-rules", "body": { "workspace": "example" } }, "effects": "May change state through POST /api/v1/{workspace}/schedule-rules. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/v1/*/schedule-rules", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "schedule_rules.update", "title": "Update schedule rule", "description": "Update a Forecast schedule rule.", "method": "PUT", "path": "/api/v1/{workspace}/schedule-rules/{ruleId}", "permission": "settings:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "ruleId": { "type": "string", "minLength": 1 }, "scenario_id": { "type": "string", "minLength": 1 }, "coa_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pattern_type": { "type": "string", "minLength": 1 }, "pattern_config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "is_active": { "type": "boolean" } }, "required": [ "workspace", "ruleId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update schedule rule.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "ruleId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/v1/example/schedule-rules/example", "body": { "workspace": "example", "ruleId": "example" } }, "effects": "May change state through PUT /api/v1/{workspace}/schedule-rules/{ruleId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/v1/*/schedule-rules/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "schedule_rules.delete", "title": "Delete schedule rule", "description": "Delete a Forecast schedule rule.", "method": "DELETE", "path": "/api/v1/{workspace}/schedule-rules/{ruleId}", "permission": "settings:write", "authorizationMode": "static", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "ruleId": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "ruleId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete schedule rule.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "ruleId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/v1/example/schedule-rules/example", "body": null }, "effects": "May change state through DELETE /api/v1/{workspace}/schedule-rules/{ruleId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/v1/*/schedule-rules/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "shares.list", "title": "Shares List", "description": "Call GET /api/v1/{workspace}/shares.", "method": "GET", "path": "/api/v1/{workspace}/shares", "permission": "forecasts:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 } }, "required": [ "workspace" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Shares List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/shares", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/shares without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/shares", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "shares.create", "title": "Shares Create", "description": "Call POST /api/v1/{workspace}/shares.", "method": "POST", "path": "/api/v1/{workspace}/shares", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "permission_level": { "type": "string", "enum": [ "read", "collaborate" ] }, "expires_at": { "type": "string", "minLength": 1 }, "max_accesses": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "recipient_user_id": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Shares Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "name": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/v1/example/shares", "body": { "workspace": "example", "name": "example" } }, "effects": "May change state through POST /api/v1/{workspace}/shares. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/v1/*/shares", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "shares.update", "title": "Shares Update", "description": "Call PATCH /api/v1/{workspace}/shares/{shareId}.", "method": "PATCH", "path": "/api/v1/{workspace}/shares/{shareId}", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "shareId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "permission_level": { "type": "string", "enum": [ "read", "collaborate" ] }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "minLength": 1 }, "max_accesses": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "workspace", "shareId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Shares Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "shareId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/v1/example/shares/example", "body": { "workspace": "example", "shareId": "example" } }, "effects": "May change state through PATCH /api/v1/{workspace}/shares/{shareId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/v1/*/shares/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "shares.delete", "title": "Shares Delete", "description": "Call DELETE /api/v1/{workspace}/shares/{shareId}.", "method": "DELETE", "path": "/api/v1/{workspace}/shares/{shareId}", "permission": "forecasts:write", "authorizationMode": "static", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "shareId": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "shareId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Shares Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example", "shareId": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/v1/example/shares/example", "body": null }, "effects": "May change state through DELETE /api/v1/{workspace}/shares/{shareId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/v1/*/shares/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "shares.settings.get", "title": "Shares Settings Get", "description": "Call GET /api/v1/{workspace}/share-settings.", "method": "GET", "path": "/api/v1/{workspace}/share-settings", "permission": "settings:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 } }, "required": [ "workspace" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Shares Settings Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/v1/example/share-settings", "body": null }, "effects": "Reads state through GET /api/v1/{workspace}/share-settings without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/v1/*/share-settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "shares.settings.update", "title": "Shares Settings Update", "description": "Call PATCH /api/v1/{workspace}/share-settings.", "method": "PATCH", "path": "/api/v1/{workspace}/share-settings", "permission": "settings:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "sharing_enabled": { "type": "boolean" }, "default_permission_level": { "type": "string", "enum": [ "read", "collaborate" ] }, "default_expiry_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_active_shares": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "require_password": { "type": "boolean" }, "allowed_domains": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "custom_branding_enabled": { "type": "boolean" }, "custom_logo_url": { "type": "string", "minLength": 1 }, "custom_title": { "type": "string", "minLength": 1 }, "custom_description": { "type": "string", "minLength": 1 }, "analytics_enabled": { "type": "boolean" } }, "required": [ "workspace" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Shares Settings Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace": "example" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/v1/example/share-settings", "body": { "workspace": "example" } }, "effects": "May change state through PATCH /api/v1/{workspace}/share-settings. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/v1/*/share-settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.export", "title": "Export organization data", "description": "Export all Forecast data owned by the authenticated organization without share credential material.", "method": "GET", "path": "/api/organizations/data/export", "permission": "privacy:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/data/export", "body": null }, "effects": "Reads state through GET /api/organizations/data/export without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/data/export", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.erase", "title": "Erase organization data", "description": "Permanently erase all Forecast data and workspace-scoped caches owned by the authenticated organization while retaining backups under policy.", "method": "DELETE", "path": "/api/organizations/data/erase", "permission": "privacy:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-forecast --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/data/erase", "body": null }, "effects": "May change state through DELETE /api/organizations/data/erase. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/data/erase", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 63, "matched_actions": 52, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 11, "configured_exclusions": 9, "configuration_findings": [], "notes": [] }, "runtime_contract_audit": { "status": "verified", "actions": 52, "contracts": 52, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/index.ts" ], "authorization_sources": [ "apps/api/src/index.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloForecast/topolo.mobile-experience.json", "contract": { "version": "2026-07-24", "status": "approved", "mode": "native_capability", "appId": "app_topolo_forecast", "localizationNamespace": "forecast", "permissions": [ "settings:read", "settings:write", "forecasts:read", "forecasts:write", "workspace:read", "workspace:write", "workspace:delete" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/dashboard/workspace", "auth": { "audience": "topolo-forecast", "scopes": [ "settings:read", "settings:write", "forecasts:read", "forecasts:write", "workspace:read", "workspace:write", "workspace:delete" ] }, "routes": [ { "path": "/dashboard/workspace", "apiPath": "/api/widget", "title": "Forecast", "titleKey": "forecast.mobile.routes.workspace.title", "template": "record.detail", "dataSource": "forecast.widget.get" }, { "path": "/chart-of-accounts", "apiPath": "/api/v1/:workspace/coa", "title": "Chart of accounts", "titleKey": "forecast.mobile.routes.chartOfAccounts.title", "template": "record.list", "dataSource": "coa.get", "detailRoute": "/chart-of-accounts/:id", "actions": [ { "id": "forecast.coa.create", "title": "Create account", "titleKey": "forecast.mobile.actions.accountCreate.title", "type": "record.create", "permission": "forecasts:write", "method": "POST", "path": "/api/v1/:workspace/coa", "fields": [ { "key": "name", "label": "Name", "type": "text", "required": true }, { "key": "type", "label": "Account type", "type": "text", "required": true }, { "key": "trend_factor", "label": "Trend factor", "type": "number" }, { "key": "parentId", "label": "Parent account", "type": "text" }, { "key": "order_index", "label": "Order", "type": "number" } ] }, { "id": "forecast.coa.update", "title": "Update account", "titleKey": "forecast.mobile.actions.accountUpdate.title", "type": "record.update", "permission": "forecasts:write", "method": "PATCH", "path": "/api/v1/:workspace/coa/:id", "fields": [ { "key": "name", "label": "Name", "type": "text" }, { "key": "type", "label": "Account type", "type": "text" }, { "key": "trend_factor", "label": "Trend factor", "type": "number" }, { "key": "parentId", "label": "Parent account", "type": "text" } ] }, { "id": "forecast.coa.delete", "title": "Delete account", "titleKey": "forecast.mobile.actions.accountDelete.title", "type": "record.delete", "permission": "forecasts:write", "method": "DELETE", "path": "/api/v1/:workspace/coa/:id" } ] } ], "notes": "The native shell owns canonical workspace selection and Topolo Auth owns list/create/rename/default. Forecast exposes the selected workspace summary and app-local domain actions only." } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "LITERAL", "path": "/clear", "source_path": "apps/TopoloForecast/apps/api/src/durable-objects/cache-store.ts" }, { "method": "GET", "path": "/health", "source_path": "apps/TopoloForecast/apps/api/src/index.ts" }, { "method": "GET", "path": "/widget", "source_path": "apps/TopoloForecast/apps/api/src/index.ts" }, { "method": "GET", "path": "/organizations/data/export", "source_path": "apps/TopoloForecast/apps/api/src/index.ts" }, { "method": "DELETE", "path": "/organizations/data/erase", "source_path": "apps/TopoloForecast/apps/api/src/index.ts" }, { "method": "GET", "path": "/v1/:workspace/health", "source_path": "apps/TopoloForecast/apps/api/src/index.ts" }, { "method": "GET", "path": "/test", "source_path": "apps/TopoloForecast/apps/api/src/router.ts" }, { "method": "GET", "path": "/:workspace/cash-accounts", "source_path": "apps/TopoloForecast/apps/api/src/routes/cash.ts" }, { "method": "POST", "path": "/:workspace/cash-accounts", "source_path": "apps/TopoloForecast/apps/api/src/routes/cash.ts" }, { "method": "PATCH", "path": "/:workspace/cash-accounts/:accountId", "source_path": "apps/TopoloForecast/apps/api/src/routes/cash.ts" }, { "method": "DELETE", "path": "/:workspace/cash-accounts/:accountId", "source_path": "apps/TopoloForecast/apps/api/src/routes/cash.ts" }, { "method": "GET", "path": "/:workspace/cash-flow/:period", "source_path": "apps/TopoloForecast/apps/api/src/routes/cash.ts" }, { "method": "POST", "path": "/:workspace/cash-flow", "source_path": "apps/TopoloForecast/apps/api/src/routes/cash.ts" }, { "method": "PATCH", "path": "/:workspace/cash-flow/:entryId", "source_path": "apps/TopoloForecast/apps/api/src/routes/cash.ts" }, { "method": "DELETE", "path": "/:workspace/cash-flow/:entryId", "source_path": "apps/TopoloForecast/apps/api/src/routes/cash.ts" }, { "method": "GET", "path": "/:workspace/cash-settings", "source_path": "apps/TopoloForecast/apps/api/src/routes/cash.ts" }, { "method": "PATCH", "path": "/:workspace/cash-settings", "source_path": "apps/TopoloForecast/apps/api/src/routes/cash.ts" }, { "method": "GET", "path": "/:workspace/schedule-rules", "source_path": "apps/TopoloForecast/apps/api/src/routes/cash.ts" }, { "method": "POST", "path": "/:workspace/schedule-rules", "source_path": "apps/TopoloForecast/apps/api/src/routes/cash.ts" }, { "method": "PUT", "path": "/:workspace/schedule-rules/:ruleId", "source_path": "apps/TopoloForecast/apps/api/src/routes/cash.ts" }, { "method": "DELETE", "path": "/:workspace/schedule-rules/:ruleId", "source_path": "apps/TopoloForecast/apps/api/src/routes/cash.ts" }, { "method": "GET", "path": "/:workspace/coa", "source_path": "apps/TopoloForecast/apps/api/src/routes/coa.ts" }, { "method": "POST", "path": "/:workspace/coa", "source_path": "apps/TopoloForecast/apps/api/src/routes/coa.ts" }, { "method": "PATCH", "path": "/:workspace/coa/:id", "source_path": "apps/TopoloForecast/apps/api/src/routes/coa.ts" }, { "method": "DELETE", "path": "/:workspace/coa/:id", "source_path": "apps/TopoloForecast/apps/api/src/routes/coa.ts" }, { "method": "GET", "path": "/:workspace/daily/:period", "source_path": "apps/TopoloForecast/apps/api/src/routes/daily-entries.ts" }, { "method": "GET", "path": "/:workspace/daily/annual/:year", "source_path": "apps/TopoloForecast/apps/api/src/routes/daily-entries.ts" }, { "method": "PUT", "path": "/:workspace/daily", "source_path": "apps/TopoloForecast/apps/api/src/routes/daily-entries.ts" }, { "method": "PUT", "path": "/:workspace/daily/bulk", "source_path": "apps/TopoloForecast/apps/api/src/routes/daily-entries.ts" }, { "method": "POST", "path": "/:workspace/imports", "source_path": "apps/TopoloForecast/apps/api/src/routes/imports.ts" }, { "method": "GET", "path": "/:workspace/shares", "source_path": "apps/TopoloForecast/apps/api/src/routes/legacy-workspace-shares.ts" }, { "method": "POST", "path": "/:workspace/shares", "source_path": "apps/TopoloForecast/apps/api/src/routes/legacy-workspace-shares.ts" }, { "method": "PATCH", "path": "/:workspace/shares/:shareId", "source_path": "apps/TopoloForecast/apps/api/src/routes/legacy-workspace-shares.ts" }, { "method": "DELETE", "path": "/:workspace/shares/:shareId", "source_path": "apps/TopoloForecast/apps/api/src/routes/legacy-workspace-shares.ts" }, { "method": "GET", "path": "/:workspace/share-settings", "source_path": "apps/TopoloForecast/apps/api/src/routes/legacy-workspace-shares.ts" }, { "method": "PATCH", "path": "/:workspace/share-settings", "source_path": "apps/TopoloForecast/apps/api/src/routes/legacy-workspace-shares.ts" }, { "method": "GET", "path": "/:workspace/openclaw/events", "source_path": "apps/TopoloForecast/apps/api/src/routes/openclaw.ts" }, { "method": "GET", "path": "/:workspace/openclaw/forecast-health", "source_path": "apps/TopoloForecast/apps/api/src/routes/openclaw.ts" }, { "method": "POST", "path": "/:workspace/openclaw/report-status", "source_path": "apps/TopoloForecast/apps/api/src/routes/openclaw.ts" }, { "method": "POST", "path": "/:workspace/openclaw/export-status", "source_path": "apps/TopoloForecast/apps/api/src/routes/openclaw.ts" }, { "method": "GET", "path": "/v1/:workspace/scenarios", "source_path": "apps/TopoloForecast/apps/api/src/routes/scenarios.ts" }, { "method": "POST", "path": "/v1/:workspace/scenarios", "source_path": "apps/TopoloForecast/apps/api/src/routes/scenarios.ts" }, { "method": "PATCH", "path": "/v1/:workspace/scenarios/:scenarioId", "source_path": "apps/TopoloForecast/apps/api/src/routes/scenarios.ts" }, { "method": "POST", "path": "/v1/:workspace/scenarios/:scenarioId/duplicate", "source_path": "apps/TopoloForecast/apps/api/src/routes/scenarios.ts" }, { "method": "DELETE", "path": "/v1/:workspace/scenarios/:scenarioId", "source_path": "apps/TopoloForecast/apps/api/src/routes/scenarios.ts" }, { "method": "GET", "path": "/shared/:shareToken", "source_path": "apps/TopoloForecast/apps/api/src/routes/shared-access.ts" }, { "method": "GET", "path": "/shared/:shareToken/coa", "source_path": "apps/TopoloForecast/apps/api/src/routes/shared-access.ts" }, { "method": "GET", "path": "/shared/:shareToken/daily/:period", "source_path": "apps/TopoloForecast/apps/api/src/routes/shared-access.ts" }, { "method": "GET", "path": "/shared/:shareToken/daily/annual/:year", "source_path": "apps/TopoloForecast/apps/api/src/routes/shared-access.ts" }, { "method": "PUT", "path": "/shared/:shareToken/daily", "source_path": "apps/TopoloForecast/apps/api/src/routes/shared-access.ts" }, { "method": "GET", "path": "/shared/:shareToken/schedule-rules", "source_path": "apps/TopoloForecast/apps/api/src/routes/shared-access.ts" }, { "method": "GET", "path": "/:workspace/summary/month/:period", "source_path": "apps/TopoloForecast/apps/api/src/routes/summary-forecast.ts" }, { "method": "GET", "path": "/:workspace/summary/year/:period", "source_path": "apps/TopoloForecast/apps/api/src/routes/summary-forecast.ts" }, { "method": "GET", "path": "/:workspace/forecast/:period", "source_path": "apps/TopoloForecast/apps/api/src/routes/summary-forecast.ts" }, { "method": "GET", "path": "/v1/workspaces/:workspaceId/shares", "source_path": "apps/TopoloForecast/apps/api/src/routes/workspace-shares.ts" }, { "method": "POST", "path": "/v1/workspaces/:workspaceId/shares", "source_path": "apps/TopoloForecast/apps/api/src/routes/workspace-shares.ts" }, { "method": "PATCH", "path": "/v1/workspaces/:workspaceId/shares/:shareId", "source_path": "apps/TopoloForecast/apps/api/src/routes/workspace-shares.ts" }, { "method": "DELETE", "path": "/v1/workspaces/:workspaceId/shares/:shareId", "source_path": "apps/TopoloForecast/apps/api/src/routes/workspace-shares.ts" }, { "method": "GET", "path": "/v1/workspaces/:workspaceId/share-settings", "source_path": "apps/TopoloForecast/apps/api/src/routes/workspace-shares.ts" }, { "method": "PATCH", "path": "/v1/workspaces/:workspaceId/share-settings", "source_path": "apps/TopoloForecast/apps/api/src/routes/workspace-shares.ts" }, { "method": "PATCH", "path": "/v1/workspaces/:id/active-scenario", "source_path": "apps/TopoloForecast/apps/api/src/routes/workspaces.ts" }, { "method": "DELETE", "path": "/v1/workspaces/:id", "source_path": "apps/TopoloForecast/apps/api/src/routes/workspaces.ts" } ], "ui_routes": [ { "path": "/cash", "source_path": "apps/TopoloForecast/apps/api/src/forecast-notifications.ts" }, { "path": "/schedule-rules", "source_path": "apps/TopoloForecast/apps/api/src/forecast-notifications.ts" }, { "path": "/imports/${encodeURIComponent(importId)}", "source_path": "apps/TopoloForecast/apps/api/src/routes/imports.ts" }, { "path": "/scenarios/${encodeURIComponent(scenarioId)}", "source_path": "apps/TopoloForecast/apps/api/src/routes/scenarios.ts" }, { "path": "/shared/${encodeURIComponent(token)}", "source_path": "apps/TopoloForecast/apps/api/src/routes/workspace-shares.ts" }, { "path": "/month/:yearMonth", "source_path": "apps/TopoloForecast/apps/web/src/App.tsx" }, { "path": "/annual/:year", "source_path": "apps/TopoloForecast/apps/web/src/App.tsx" }, { "path": "/dashboard", "source_path": "apps/TopoloForecast/apps/web/src/App.tsx" }, { "path": "/dashboard/:year", "source_path": "apps/TopoloForecast/apps/web/src/App.tsx" }, { "path": "/scenarios", "source_path": "apps/TopoloForecast/apps/web/src/App.tsx" }, { "path": "/settings", "source_path": "apps/TopoloForecast/apps/web/src/App.tsx" }, { "path": "/settings/:section", "source_path": "apps/TopoloForecast/apps/web/src/App.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloForecast/apps/web/src/App.tsx" }, { "path": "/error/:code?", "source_path": "apps/TopoloForecast/apps/web/src/App.tsx" }, { "path": "/shared/:shareToken", "source_path": "apps/TopoloForecast/apps/web/src/App.tsx" }, { "path": "/shared/:shareToken/month/:yearMonth", "source_path": "apps/TopoloForecast/apps/web/src/App.tsx" }, { "path": "/shared/:shareToken/annual/:year", "source_path": "apps/TopoloForecast/apps/web/src/App.tsx" }, { "path": "/shared/:shareToken/dashboard/:year", "source_path": "apps/TopoloForecast/apps/web/src/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "internal/apps/forecast", "applications/forecast" ], "present_paths": [ "internal/apps/forecast", "applications/forecast" ], "missing_paths": [], "human_reference": "/systems/topolo-forecast", "machine_reference": "/machine/systems/topolo-forecast.json", "action_examples": 52, "action_schemas": 52 }, "source_findings": [] }, "topolo-mcp": { "id": "topolo-mcp", "name": "Topolo MCP", "slug": "topolo-mcp", "kind": "tool", "visibility": "public", "repo_paths": [ "topolo-platform/packages/topolo-mcp" ], "source_revisions": [ { "source_path": "topolo-platform/packages/topolo-mcp", "repository": "topolo-platform", "revision": "515376de81efed9734741b2a1d691c8195243073", "ref": "origin/staging" } ], "source_counts": { "source_files": 15, "test_files": 11, "test_cases": 0, "migration_files": 0, "database_tables": 0, "manifests": 0, "deploy_targets": 0, "actions": 0, "mobile_contracts": 0, "notifications": 0, "package_manifests": 1, "deployment_configs": 0 }, "manifests": [], "mobile_contracts": [], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [], "ui_routes": [], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "guides/agents-and-automation", "internal/apps/topolo-mcp" ], "present_paths": [ "guides/agents-and-automation", "internal/apps/topolo-mcp" ], "missing_paths": [], "human_reference": "/systems/topolo-mcp", "machine_reference": "/machine/systems/topolo-mcp.json", "action_examples": 0, "action_schemas": 0 }, "source_findings": [] }, "topolo-mdm": { "id": "topolo-mdm", "name": "TopoloMDM", "slug": "topolo-mdm", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloMDM" ], "source_revisions": [ { "source_path": "apps/TopoloMDM", "repository": "apps/TopoloMDM", "revision": "eaf9d5e2bc22504ac71ee1143b78da9e3b1b810f", "ref": "origin/staging" } ], "source_counts": { "source_files": 189, "test_files": 64, "test_cases": 0, "migration_files": 0, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 23, "mobile_contracts": 1, "notifications": 8, "package_manifests": 3, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloMDM/topolo.app.json", "service_slug": "topolo-mdm", "name": "TopoloMDM", "app_id": "app_topolo_mdm", "compatibility_date": "2026-04-10", "primary_target": null, "environments": [ "production", "staging" ], "targets": [ { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-mdm-console", "subdomain": "mdm", "healthcheck_path": null, "variable_names": [ "APP_CATALOG_URL", "AUTH_API_URL", "FEED_API_URL", "INSIGHTS_SITE_KEY", "STATE_API_URL" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null } ] }, { "name": "api", "kind": "worker", "directory": "apps/api", "main": "index.js", "worker_name": "topolo-mdm-api", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "APP_CATALOG_URL", "AUTH_BASE_URL", "FEED_API_URL", "MDM_CONSOLE_APP_ID", "MDM_PUBLIC_BASE_URL", "STATE_API_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "kv", "binding": "TOPOLO_STATE", "target": null }, { "kind": "durableObjects", "binding": "WORKSPACE_EVENTS", "target": null }, { "kind": "durableObjects", "binding": "WORKSPACE_STATE", "target": null } ] } ], "notifications": [ "mdm.command.completed", "mdm.command.failed", "mdm.device.noncompliant", "mdm.device.offline", "mdm.enrollment.completed", "mdm.enrollment.failed", "mdm.enrollment.requested", "mdm.profile.changed" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_mdm", "events": [ { "type": "mdm.command.completed", "version": 1, "description": "A managed device durably recorded successful completion of an operator-issued command.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "command_id", "device_id", "command_action", "status", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "command_id": { "type": "string", "minLength": 1 }, "device_id": { "type": "string", "minLength": 1 }, "command_action": { "type": "string", "minLength": 1 }, "status": { "const": "completed" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "examples": [ { "title": "Command completed: install", "body": "The install command completed.", "object_id": "cmd_123", "command_id": "cmd_123", "device_id": "device_123", "command_action": "install", "status": "completed", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^mdm:command-completed:" } }, { "type": "mdm.command.failed", "version": 1, "description": "A managed device durably recorded failure of an operator-issued command.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "command_id", "device_id", "command_action", "status", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "command_id": { "type": "string", "minLength": 1 }, "device_id": { "type": "string", "minLength": 1 }, "command_action": { "type": "string", "minLength": 1 }, "status": { "const": "failed" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "examples": [ { "title": "Command failed: install", "body": "The install command failed.", "object_id": "cmd_123", "command_id": "cmd_123", "device_id": "device_123", "command_action": "install", "status": "failed", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^mdm:command-failed:" } }, { "type": "mdm.device.noncompliant", "version": 1, "description": "A managed device durably transitioned from a compliant state to a noncompliant policy state.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "device_id", "reasons", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "device_id": { "type": "string", "minLength": 1 }, "reasons": { "type": "array", "items": { "type": "string" } }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "examples": [ { "title": "Device noncompliant: device_123", "body": "Required policy is not applied.", "object_id": "device_123", "device_id": "device_123", "reasons": [ "Required policy is not applied" ], "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^mdm:device-noncompliant:" } }, { "type": "mdm.device.offline", "version": 1, "description": "The scheduled MDM reconciler durably detected that an enrolled device crossed the offline threshold.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "device_id", "last_seen_at", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "device_id": { "type": "string", "minLength": 1 }, "last_seen_at": { "type": "string", "format": "date-time" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "examples": [ { "title": "Device offline: device_123", "body": "The device has not checked in for 15 minutes.", "object_id": "device_123", "device_id": "device_123", "last_seen_at": "2026-07-20T11:45:00.000Z", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^mdm:device-offline:" } }, { "type": "mdm.enrollment.completed", "version": 1, "description": "A device durably completed an accepted MDM enrollment session.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "device_id", "enrollment_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "device_id": { "type": "string", "minLength": 1 }, "enrollment_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "examples": [ { "title": "Device enrolled: device_123", "body": "The device completed MDM enrollment.", "object_id": "device_123", "device_id": "device_123", "enrollment_id": "enrollment_hash_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^mdm:enrollment-completed:" } }, { "type": "mdm.enrollment.failed", "version": 1, "description": "MDM persisted a device registration failure after accepting a valid enrollment session.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "device_id", "enrollment_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "device_id": { "type": "string", "minLength": 1 }, "enrollment_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "examples": [ { "title": "Device enrollment failed: device_123", "body": "The accepted enrollment session did not complete device registration.", "object_id": "device_123", "device_id": "device_123", "enrollment_id": "enrollment_hash_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^mdm:enrollment-failed:" } }, { "type": "mdm.enrollment.requested", "version": 1, "description": "An operator durably created a time-limited MDM enrollment session.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "enrollment_id", "expires_at", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "enrollment_id": { "type": "string", "minLength": 1 }, "expires_at": { "type": "string", "format": "date-time" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "examples": [ { "title": "Device enrollment requested", "body": "A new MDM device enrollment session is ready.", "object_id": "enrollment_hash_123", "enrollment_id": "enrollment_hash_123", "expires_at": "2026-07-20T12:30:00.000Z", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^mdm:enrollment-requested:" } }, { "type": "mdm.profile.changed", "version": 1, "description": "An operator durably changed a managed device profile and its derived command plan.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "device_id", "profile_mode", "policy_preset", "queued_command_count", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "device_id": { "type": "string", "minLength": 1 }, "profile_mode": { "type": "string", "minLength": 1 }, "policy_preset": { "type": "string", "minLength": 1 }, "queued_command_count": { "type": "integer", "minimum": 0 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "examples": [ { "title": "Device profile changed: device_123", "body": "The device is now using the business_lockdown policy preset.", "object_id": "device_123", "device_id": "device_123", "profile_mode": "business_display", "policy_preset": "business_lockdown", "queued_command_count": 2, "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^mdm:profile-changed:" } } ] }, "actions": [ { "name": "workspaces.delete", "title": "Archive MDM workspace", "description": "Archive an empty MDM workspace. The platform owns the workspace record; this app confirms it holds no devices and asks Auth to archive it.", "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "method": "DELETE", "path": "/api/workspaces/{workspaceId}", "permission": "workspace:delete", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.data.export", "title": "Export MDM workspace data", "description": "Export the MDM-owned device, enrollment, notification, assignment, and retained event data for one authorized workspace with credentials redacted.", "target": "api", "method": "GET", "path": "/api/workspaces/{workspaceId}/data", "permission": "workspace:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/data", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceId}/data without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.data.erase", "title": "Erase MDM workspace data", "description": "Permanently erase all MDM-owned data for one authorized workspace while preserving the canonical Auth workspace and credentials.", "target": "api", "method": "DELETE", "path": "/api/workspaces/{workspaceId}/data", "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 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/workspaces/example/data", "body": null }, "effects": "May change state through DELETE /api/workspaces/{workspaceId}/data. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/workspaces/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "dashboard: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-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "fleet.get", "title": "Get fleet report", "description": "Get the MDM OpenClaw fleet report.", "method": "GET", "path": "/api/openclaw/fleet", "permission": "reports:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get fleet report.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/openclaw/fleet", "body": null }, "effects": "Reads state through GET /api/openclaw/fleet without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/openclaw/fleet", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "events.list", "title": "List fleet events", "description": "List MDM OpenClaw events.", "method": "GET", "path": "/api/openclaw/events", "permission": "reports:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "since": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List fleet events.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "since": "example", "limit": 1 }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/openclaw/events", "body": null }, "effects": "Reads state through GET /api/openclaw/events without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/openclaw/events", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operator_events.list", "title": "List operator events", "description": "List MDM operator events.", "method": "GET", "path": "/api/events", "permission": "dashboard:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List operator events.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/events", "body": null }, "effects": "Reads state through GET /api/events without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/events", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "enrollment_sessions.create", "title": "Create enrollment session", "description": "Create an MDM enrollment session.", "method": "POST", "path": "/api/enrollment-sessions", "permission": "devices:control", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create enrollment session.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspace_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/enrollment-sessions", "body": { "workspace_id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/enrollment-sessions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/enrollment-sessions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "devices.list", "title": "List devices", "description": "List MDM devices.", "method": "GET", "path": "/api/devices", "permission": "devices:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List devices.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/devices", "body": null }, "effects": "Reads state through GET /api/devices without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/devices", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "devices.admin_list", "title": "Admin list devices", "description": "List MDM devices with admin scope.", "method": "GET", "path": "/api/admin/devices", "permission": "devices:admin", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "filter_workspace_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Admin list devices.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "filter_workspace_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/devices", "body": null }, "effects": "Reads state through GET /api/admin/devices without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/devices", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "devices.delete", "title": "Delete device", "description": "Delete an MDM device.", "method": "DELETE", "path": "/api/devices/{deviceId}", "permission": "devices:write", "authorizationMode": "static", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "required": [ "deviceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete device.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "documentation": { "example_input": { "deviceId": "example" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/devices/example", "body": null }, "effects": "May change state through DELETE /api/devices/{deviceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/devices/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "devices.dump.get", "title": "Get device dump", "description": "Get an MDM device dump.", "method": "GET", "path": "/api/device-dump/{deviceId}", "permission": "devices:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "required": [ "deviceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get device dump.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "deviceId": "example" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/device-dump/example", "body": null }, "effects": "Reads state through GET /api/device-dump/{deviceId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/device-dump/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "devices.debug.get", "title": "Get device debug", "description": "Get MDM device debug data.", "method": "GET", "path": "/api/devices/{deviceId}/debug", "permission": "devices:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "required": [ "deviceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get device debug.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "deviceId": "example" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/devices/example/debug", "body": null }, "effects": "Reads state through GET /api/devices/{deviceId}/debug without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/devices/*/debug", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "devices.info.update", "title": "Update device info", "description": "Update MDM device info.", "method": "POST", "path": "/api/device-info/{deviceId}", "permission": "devices:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "installedPackages": { "type": "array", "items": {} }, "metrics": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "deviceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update device info.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "deviceId": "example" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/device-info/example", "body": { "deviceId": "example" } }, "effects": "May change state through POST /api/device-info/{deviceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/device-info/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "devices.account.register", "title": "Register device account", "description": "Register an MDM device account.", "method": "POST", "path": "/api/register-account/{deviceId}", "permission": "devices:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "accountNumber": { "type": "string", "minLength": 1 } }, "required": [ "deviceId", "accountNumber" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Register device account.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "deviceId": "example", "accountNumber": "example" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/register-account/example", "body": { "deviceId": "example", "accountNumber": "example" } }, "effects": "May change state through POST /api/register-account/{deviceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/register-account/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "devices.account_id.update", "title": "Update device account id", "description": "Update an MDM device account id.", "method": "POST", "path": "/api/update-account-id/{deviceId}", "permission": "devices:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "accountNumber": { "type": "string", "minLength": 1 } }, "required": [ "deviceId", "accountNumber" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update device account id.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "deviceId": "example", "accountNumber": "example" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/update-account-id/example", "body": { "deviceId": "example", "accountNumber": "example" } }, "effects": "May change state through POST /api/update-account-id/{deviceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/update-account-id/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "devices.account_info.update", "title": "Update device account info", "description": "Update MDM device account info.", "method": "POST", "path": "/api/update-account-info/{deviceId}", "permission": "devices:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "accountInfo": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "deviceId", "accountInfo" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update device account info.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "deviceId": "example", "accountInfo": {} }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/update-account-info/example", "body": { "deviceId": "example", "accountInfo": {} } }, "effects": "May change state through POST /api/update-account-info/{deviceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/update-account-info/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "device_profiles.list", "title": "List device profiles", "description": "List MDM device profiles.", "method": "GET", "path": "/api/device-profiles", "permission": "policies:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List device profiles.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspace_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/device-profiles", "body": null }, "effects": "Reads state through GET /api/device-profiles without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/device-profiles", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "device_profiles.get", "title": "Get device profile", "description": "Get an MDM device profile.", "method": "GET", "path": "/api/device-profiles/{deviceId}", "permission": "policies:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "required": [ "deviceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get device profile.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "deviceId": "example" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/device-profiles/example", "body": null }, "effects": "Reads state through GET /api/device-profiles/{deviceId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/device-profiles/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "device_profiles.upsert", "title": "Upsert device profile", "description": "Upsert an MDM device profile.", "method": "PUT", "path": "/api/device-profiles/{deviceId}", "permission": "policies:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "profile": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "deviceId", "profile" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Upsert device profile.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "deviceId": "example", "profile": {} }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/device-profiles/example", "body": { "deviceId": "example", "profile": {} } }, "effects": "May change state through PUT /api/device-profiles/{deviceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/device-profiles/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "commands.enqueue", "title": "Enqueue command", "description": "Enqueue an MDM device command.", "method": "POST", "path": "/api/enqueue", "permission": "commands:invoke", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "minLength": 1 }, "deviceId": { "type": "string", "minLength": 1 }, "command": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "action": { "type": "string", "minLength": 1 } }, "required": [ "id", "action" ], "additionalProperties": {} } }, "required": [ "deviceId", "command" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Enqueue command.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "deviceId": "example", "command": { "id": "00000000-0000-4000-8000-000000000000", "action": "example" } }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/enqueue", "body": { "deviceId": "example", "command": { "id": "00000000-0000-4000-8000-000000000000", "action": "example" } } }, "effects": "May change state through POST /api/enqueue. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/enqueue", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "commands.clear", "title": "Clear commands", "description": "Clear queued MDM device commands.", "method": "POST", "path": "/api/clear-commands", "permission": "commands:invoke", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "minLength": 1 }, "deviceId": { "type": "string", "minLength": 1 } }, "required": [ "deviceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Clear commands.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "deviceId": "example" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/clear-commands", "body": { "deviceId": "example" } }, "effects": "May change state through POST /api/clear-commands. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/clear-commands", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "commands.history.get", "title": "Get command history", "description": "Get MDM command history for a device.", "method": "GET", "path": "/api/command-history/{deviceId}", "permission": "devices:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "required": [ "deviceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get command history.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "deviceId": "example" }, "cli_example": [ "topolo actions --service topolo-mdm --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/command-history/example", "body": null }, "effects": "Reads state through GET /api/command-history/{deviceId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/command-history/*", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 40, "matched_actions": 23, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 17, "configured_exclusions": 15, "configuration_findings": [], "notes": [] }, "runtime_contract_audit": { "status": "verified", "actions": 23, "contracts": 23, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/index.js" ], "authorization_sources": [ "apps/api/index.js" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloMDM/topolo.mobile-experience.json", "contract": { "version": "1.0.0", "status": "published", "mode": "native_capability", "appId": "app_topolo_mdm", "localizationNamespace": "mdm", "permissions": [ "devices:read", "policies:read", "apps:read" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/devices", "auth": { "audience": "topolo-mdm", "scopes": [ "devices:read", "policies:read", "apps:read" ] }, "routes": [ { "path": "/devices", "apiPath": "/api/devices", "title": "Devices", "titleKey": "mdm.mobile.intl.devices-title", "template": "record.list", "dataSource": "mdm.devices.list" }, { "path": "/device-profiles", "apiPath": "/api/device-profiles", "title": "Device profiles", "titleKey": "mdm.mobile.routes.deviceProfiles.title", "template": "record.list", "dataSource": "mdm.deviceProfiles.list", "detailRoute": "/device-profiles/:id" }, { "path": "/device-profiles/:id", "apiPath": "/api/device-profiles/:id", "title": "Device profile", "titleKey": "mdm.mobile.routes.deviceProfileDetail.title", "template": "record.detail", "dataSource": "mdm.deviceProfiles.detail" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "GET", "path": "/health", "source_path": "apps/TopoloMDM/apps/api/index.js" }, { "method": "POST", "path": "/register", "source_path": "apps/TopoloMDM/apps/api/index.js" }, { "method": "POST", "path": "/poll", "source_path": "apps/TopoloMDM/apps/api/index.js" }, { "method": "POST", "path": "/device-push-token", "source_path": "apps/TopoloMDM/apps/api/index.js" }, { "method": "POST", "path": "/command-status", "source_path": "apps/TopoloMDM/apps/api/index.js" }, { "method": "GET", "path": "/device-events", "source_path": "apps/TopoloMDM/apps/api/index.js" }, { "method": "GET", "path": "/widget", "source_path": "apps/TopoloMDM/apps/api/index.js" }, { "method": "GET", "path": "/events", "source_path": "apps/TopoloMDM/apps/api/index.js" }, { "method": "GET", "path": "/me", "source_path": "apps/TopoloMDM/apps/api/index.js" }, { "method": "GET", "path": "/runtime-config", "source_path": "apps/TopoloMDM/apps/api/index.js" }, { "method": "DELETE", "path": "/workspaces/:workspaceId", "source_path": "apps/TopoloMDM/apps/api/index.js" }, { "method": "GET", "path": "/workspaces/:workspaceId/data", "source_path": "apps/TopoloMDM/apps/api/index.js" }, { "method": "DELETE", "path": "/workspaces/:workspaceId/data", "source_path": "apps/TopoloMDM/apps/api/index.js" }, { "method": "LITERAL", "path": "/data", "source_path": "apps/TopoloMDM/apps/api/realtime.js" }, { "method": "LITERAL", "path": "/connect", "source_path": "apps/TopoloMDM/apps/api/realtime.js" }, { "method": "LITERAL", "path": "/publish", "source_path": "apps/TopoloMDM/apps/api/realtime.js" }, { "method": "POST", "path": "/enqueue", "source_path": "apps/TopoloMDM/apps/api/routes/commands.js" }, { "method": "POST", "path": "/clear-commands", "source_path": "apps/TopoloMDM/apps/api/routes/commands.js" }, { "method": "GET", "path": "/command-history/:deviceId", "source_path": "apps/TopoloMDM/apps/api/routes/commands.js" }, { "method": "POST", "path": "/crash", "source_path": "apps/TopoloMDM/apps/api/routes/commands.js" }, { "method": "POST", "path": "/enrollment-sessions", "source_path": "apps/TopoloMDM/apps/api/routes/devices.js" }, { "method": "GET", "path": "/devices", "source_path": "apps/TopoloMDM/apps/api/routes/devices.js" }, { "method": "GET", "path": "/admin/devices", "source_path": "apps/TopoloMDM/apps/api/routes/devices.js" }, { "method": "DELETE", "path": "/devices/:deviceId", "source_path": "apps/TopoloMDM/apps/api/routes/devices.js" }, { "method": "GET", "path": "/device-dump/:deviceId", "source_path": "apps/TopoloMDM/apps/api/routes/devices.js" }, { "method": "GET", "path": "/devices/:deviceId/debug", "source_path": "apps/TopoloMDM/apps/api/routes/devices.js" }, { "method": "POST", "path": "/device-info/:deviceId", "source_path": "apps/TopoloMDM/apps/api/routes/devices.js" }, { "method": "GET", "path": "/device-profiles", "source_path": "apps/TopoloMDM/apps/api/routes/devices.js" }, { "method": "GET", "path": "/device-profiles/:deviceId", "source_path": "apps/TopoloMDM/apps/api/routes/devices.js" }, { "method": "PUT", "path": "/device-profiles/:deviceId", "source_path": "apps/TopoloMDM/apps/api/routes/devices.js" }, { "method": "POST", "path": "/register-account/:deviceId", "source_path": "apps/TopoloMDM/apps/api/routes/devices.js" }, { "method": "POST", "path": "/update-account-id/:deviceId", "source_path": "apps/TopoloMDM/apps/api/routes/devices.js" }, { "method": "POST", "path": "/update-account-info/:deviceId", "source_path": "apps/TopoloMDM/apps/api/routes/devices.js" }, { "method": "GET", "path": "/openclaw/fleet", "source_path": "apps/TopoloMDM/apps/api/routes/integrations.js" }, { "method": "GET", "path": "/openclaw/events", "source_path": "apps/TopoloMDM/apps/api/routes/integrations.js" }, { "method": "LITERAL", "path": "/enrollment-sessions", "source_path": "apps/TopoloMDM/apps/api/workspace-state.js" }, { "method": "LITERAL", "path": "/enrollment-sessions/consume", "source_path": "apps/TopoloMDM/apps/api/workspace-state.js" }, { "method": "LITERAL", "path": "/children", "source_path": "apps/TopoloMDM/apps/api/workspace-state.js" }, { "method": "LITERAL", "path": "/auth/callback", "source_path": "apps/TopoloMDM/apps/web/src/worker.ts" } ], "ui_routes": [ { "path": "/dashboard", "source_path": "apps/TopoloMDM/apps/web/src/App.tsx" }, { "path": "/dashboard/overview", "source_path": "apps/TopoloMDM/apps/web/src/App.tsx" }, { "path": "/dashboard/devices", "source_path": "apps/TopoloMDM/apps/web/src/App.tsx" }, { "path": "/dashboard/content", "source_path": "apps/TopoloMDM/apps/web/src/App.tsx" }, { "path": "/dashboard/apps", "source_path": "apps/TopoloMDM/apps/web/src/App.tsx" }, { "path": "/dashboard/setup", "source_path": "apps/TopoloMDM/apps/web/src/App.tsx" }, { "path": "/dashboard/getting-started", "source_path": "apps/TopoloMDM/apps/web/src/App.tsx" }, { "path": "/settings", "source_path": "apps/TopoloMDM/apps/web/src/App.tsx" }, { "path": "/settings/:section", "source_path": "apps/TopoloMDM/apps/web/src/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/mdm", "internal/apps/mdm" ], "present_paths": [ "applications/mdm", "internal/apps/mdm" ], "missing_paths": [], "human_reference": "/systems/topolo-mdm", "machine_reference": "/machine/systems/topolo-mdm.json", "action_examples": 23, "action_schemas": 23 }, "source_findings": [] }, "topolo-messages": { "id": "topolo-messages", "name": "TopoloMessages", "slug": "topolo-messages", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloMessages" ], "source_revisions": [ { "source_path": "apps/TopoloMessages", "repository": "apps/TopoloMessages", "revision": "8ad475d8acff71d013ffa7e496968950a9516a68", "ref": "origin/staging" } ], "source_counts": { "source_files": 87, "test_files": 56, "test_cases": 0, "migration_files": 18, "database_tables": 0, "manifests": 1, "deploy_targets": 3, "actions": 32, "mobile_contracts": 1, "notifications": 8, "package_manifests": 1, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloMessages/topolo.app.json", "service_slug": "topolo-messages", "name": "topolo-messages", "app_id": "app_topolo_messages", "compatibility_date": "2026-04-16", "primary_target": "web", "environments": [ "development", "production", "staging" ], "targets": [ { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/worker.ts", "worker_name": "topolo-messages-api", "subdomain": null, "healthcheck_path": "/api/health", "variable_names": [ "AUTH_API_URL", "ENVIRONMENT", "MESSAGES_INBOUND_WEBHOOK_URL", "MESSAGES_PUBLIC_BASE_URL", "NEXUS_GATEWAY_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "MESSAGES_CORE_DB", "target": null }, { "kind": "d1", "binding": "MESSAGES_TRAFFIC_DB", "target": null }, { "kind": "d1", "binding": "MESSAGES_DELIVERY_DB", "target": null }, { "kind": "r2", "binding": "MESSAGES_ARCHIVE", "target": null }, { "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 }, { "kind": "vectorize", "binding": "MESSAGES_SEMANTIC_INDEX", "target": null }, { "kind": "ai", "binding": "AI", "target": null } ] }, { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-messages", "subdomain": "messages", "healthcheck_path": "/api/health", "variable_names": [ "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null } ] }, { "name": "jobs", "kind": "worker", "directory": "apps/jobs", "main": "src/worker.ts", "worker_name": "topolo-messages-dispatch", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "AUTH_API_URL", "ENVIRONMENT", "MESSAGES_PUBLIC_BASE_URL", "NEXUS_GATEWAY_URL", "TOPOLO_NOTIFY_URL", "WHATSAPP_GRAPH_API_VERSION", "WHATSAPP_TEMPLATE_LANGUAGE_DEFAULT" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "MESSAGES_CORE_DB", "target": null }, { "kind": "d1", "binding": "MESSAGES_TRAFFIC_DB", "target": null }, { "kind": "d1", "binding": "MESSAGES_DELIVERY_DB", "target": null }, { "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": [ "messages.campaign.completed", "messages.campaign.failed", "messages.message.delivery_failed", "messages.message.received", "messages.number.verification_changed", "messages.provider.degraded", "messages.template.approved", "messages.template.rejected" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_messages", "events": [ { "type": "messages.campaign.completed", "version": 1, "description": "All recipients in a persisted Messages campaign reached a terminal state with at least one successful delivery.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "cta_url", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" }, "payload": { "type": "object", "required": [ "campaign_id", "status", "sent_count", "failed_count" ] } }, "additionalProperties": true }, "examples": [ { "title": "Campaign completed: July launch", "body": "All campaign recipients reached a terminal delivery state.", "object_id": "campaign_123", "occurred_at": "2026-07-20T12:00:00.000Z", "cta_url": "https://messages.topolo.app/campaigns/campaign_123", "payload": { "campaign_id": "campaign_123", "status": "completed", "sent_count": 10, "failed_count": 1 } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^messages:campaign-completed:" } }, { "type": "messages.campaign.failed", "version": 1, "description": "A persisted Messages campaign reached a terminal state without a successful recipient delivery.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "cta_url", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" }, "payload": { "type": "object", "required": [ "campaign_id", "status", "failed_count" ] } }, "additionalProperties": true }, "examples": [ { "title": "Campaign failed: July launch", "body": "The campaign ended without a successful recipient delivery.", "object_id": "campaign_123", "occurred_at": "2026-07-20T12:00:00.000Z", "cta_url": "https://messages.topolo.app/campaigns/campaign_123", "payload": { "campaign_id": "campaign_123", "status": "failed", "sent_count": 0, "failed_count": 10 } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^messages:campaign-failed:" } }, { "type": "messages.message.delivery_failed", "version": 1, "description": "An outbound message and its delivery job durably reached the failed state after retry policy was exhausted or dispatch was rejected.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "cta_url", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" }, "payload": { "type": "object", "required": [ "message_id", "outbound_job_id", "provider", "error" ] } }, "additionalProperties": true }, "examples": [ { "title": "Message delivery failed", "body": "Provider rejected the request.", "object_id": "message_123", "occurred_at": "2026-07-20T12:00:00.000Z", "cta_url": "https://messages.topolo.app/conversations?message=message_123", "payload": { "message_id": "message_123", "outbound_job_id": "job_123", "provider": "whatsapp_cloud_api", "error": "Provider rejected the request." } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^messages:delivery-failed:" } }, { "type": "messages.message.received", "version": 1, "description": "Messages persisted a new inbound provider message and updated its conversation unread state.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "cta_url", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" }, "payload": { "type": "object", "required": [ "message_id", "conversation_id", "contact_id", "number_id", "message_type" ] } }, "additionalProperties": true }, "examples": [ { "title": "New message received", "body": "A contact sent a new message to your shared inbox.", "object_id": "message_123", "occurred_at": "2026-07-20T12:00:00.000Z", "cta_url": "https://messages.topolo.app/conversations/conversation_123", "payload": { "message_id": "message_123", "conversation_id": "conversation_123", "contact_id": "contact_123", "number_id": "number_123", "message_type": "text" } } ], "dataClassification": "confidential", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^messages:message-received:" } }, { "type": "messages.number.verification_changed", "version": 1, "description": "Messages durably mirrored an approved or rejected provider display-name verification decision for a connected number.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "cta_url", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" }, "payload": { "type": "object", "required": [ "number_id", "status", "decision" ] } }, "additionalProperties": true }, "examples": [ { "title": "Number verification approved", "body": "Meta approved the verified display name for this number.", "object_id": "number_123", "occurred_at": "2026-07-20T12:00:00.000Z", "cta_url": "https://messages.topolo.app/settings/numbers/number_123", "payload": { "number_id": "number_123", "status": "verified", "decision": "approved" } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^messages:number-verification:" } }, { "type": "messages.provider.degraded", "version": 1, "description": "Messages persisted an open provider incident after a provider/configuration failure made an outbound job terminal.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "cta_url", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" }, "payload": { "type": "object", "required": [ "incident_id", "provider", "outbound_job_id", "reason", "status" ] } }, "additionalProperties": true }, "examples": [ { "title": "Messaging provider degraded", "body": "Provider is unavailable.", "object_id": "incident_123", "occurred_at": "2026-07-20T12:00:00.000Z", "cta_url": "https://messages.topolo.app/settings/providers", "payload": { "incident_id": "incident_123", "provider": "whatsapp_cloud_api", "outbound_job_id": "job_123", "reason": "Provider is unavailable.", "status": "open" } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^messages:provider-degraded:" } }, { "type": "messages.template.approved", "version": 1, "description": "Messages durably mirrored Meta approval of an app-created message template.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "cta_url", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" }, "payload": { "type": "object", "required": [ "template_id", "status" ] } }, "additionalProperties": true }, "examples": [ { "title": "Template approved: order_update", "body": "Meta approved this message template for sending.", "object_id": "template_123", "occurred_at": "2026-07-20T12:00:00.000Z", "cta_url": "https://messages.topolo.app/templates/template_123", "payload": { "template_id": "template_123", "template_name": "order_update", "status": "approved" } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^messages:template-approved:" } }, { "type": "messages.template.rejected", "version": 1, "description": "Messages durably mirrored Meta rejection of an app-created message template.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "cta_url", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" }, "payload": { "type": "object", "required": [ "template_id", "status" ] } }, "additionalProperties": true }, "examples": [ { "title": "Template rejected: order_update", "body": "Meta rejected this message template.", "object_id": "template_123", "occurred_at": "2026-07-20T12:00:00.000Z", "cta_url": "https://messages.topolo.app/templates/template_123", "payload": { "template_id": "template_123", "template_name": "order_update", "status": "rejected" } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "sensitiveFields": [], "idempotency": { "required": true, "pattern": "^messages:template-rejected:" } } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "context:read", "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-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "declared_unserved", "route_key": "GET /api/widget", "evidence": "No matching served route was extracted from canonical staging source." } }, { "name": "bootstrap.get", "title": "Get messages bootstrap", "description": "Get Messages workspace bootstrap data.", "method": "GET", "path": "/api/messages/bootstrap", "permission": "inbox:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get messages bootstrap.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/bootstrap", "body": null }, "effects": "Reads state through GET /api/messages/bootstrap without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/bootstrap", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "analytics.get", "title": "Get messages analytics", "description": "Get messaging volume, delivery, contact consent, and campaign health metrics.", "method": "GET", "path": "/api/messages/analytics", "permission": "inbox:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get messages analytics.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/analytics", "body": null }, "effects": "Reads state through GET /api/messages/analytics without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/analytics", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "provider_status.get", "title": "Get messages provider status", "description": "Get WhatsApp provider queue, webhook, and runtime configuration status for a Messages workspace.", "method": "GET", "path": "/api/messages/provider-status", "permission": "inbox:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get messages provider status.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/provider-status", "body": null }, "effects": "Reads state through GET /api/messages/provider-status without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/provider-status", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "conversations.list", "title": "List conversations", "description": "List message conversations.", "method": "GET", "path": "/api/messages/conversations", "permission": "inbox:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List conversations.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/conversations", "body": null }, "effects": "Reads state through GET /api/messages/conversations without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/conversations", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "contacts.list", "title": "List contacts", "description": "List WhatsApp contacts, consent state, and recent conversation activity.", "method": "GET", "path": "/api/messages/contacts", "permission": "inbox:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "consentStatus": { "type": "string", "enum": [ "unknown", "opted_in", "opted_out" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 250 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List contacts.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example", "consentStatus": "unknown", "limit": 1 }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/contacts", "body": null }, "effects": "Reads state through GET /api/messages/contacts without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/contacts", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "contacts.update", "title": "Update contact", "description": "Update a WhatsApp contact consent state.", "method": "PATCH", "path": "/api/messages/contacts/{contactId}", "permission": "messages:send", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 }, "consentStatus": { "type": "string", "enum": [ "unknown", "opted_in", "opted_out" ] } }, "required": [ "contactId", "consentStatus" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update contact.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "contactId": "example", "consentStatus": "unknown" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/messages/contacts/example", "body": { "contactId": "example", "consentStatus": "unknown" } }, "effects": "May change state through PATCH /api/messages/contacts/{contactId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/messages/contacts/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "conversations.update", "title": "Update conversation", "description": "Update a messaging conversation state, assignment, follow-up, or contact context.", "method": "PATCH", "path": "/api/messages/conversations/{conversationId}", "permission": "messages:send", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "state": { "type": "string", "enum": [ "open", "pending", "resolved", "archived" ] }, "assignedToUserId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "assignToMe": { "type": "boolean" }, "clearAssignment": { "type": "boolean" }, "markRead": { "type": "boolean" }, "contactConsentStatus": { "type": "string", "enum": [ "unknown", "opted_in", "opted_out" ] }, "priority": { "type": "string", "enum": [ "normal", "high", "urgent" ] }, "internalNote": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "followUpAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "conversationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update conversation.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "conversationId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/messages/conversations/example", "body": { "conversationId": "example" } }, "effects": "May change state through PATCH /api/messages/conversations/{conversationId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/messages/conversations/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "messages.send", "title": "Send message", "description": "Send an outbound message.", "method": "POST", "path": "/api/messages/messages/send", "permission": "messages:send", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "numberId": { "type": "string", "minLength": 1 }, "messageType": { "type": "string", "enum": [ "text", "template" ] }, "body": { "type": "string", "minLength": 1 }, "templateName": { "type": "string", "minLength": 1 }, "recipientPhone": { "type": "string", "minLength": 1 }, "phoneNumber": { "type": "string", "minLength": 1 }, "waId": { "type": "string", "minLength": 1 }, "recipientName": { "type": "string", "minLength": 1 }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "numberId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Send message.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "numberId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/messages/messages/send", "body": { "numberId": "example" } }, "effects": "May change state through POST /api/messages/messages/send. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/messages/messages/send", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.list", "title": "List campaigns", "description": "List messaging campaigns.", "method": "GET", "path": "/api/messages/campaigns", "permission": "campaigns:manage", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List campaigns.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/campaigns", "body": null }, "effects": "Reads state through GET /api/messages/campaigns without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/campaigns", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "templates.list", "title": "List templates", "description": "List WhatsApp message templates.", "method": "GET", "path": "/api/messages/templates", "permission": "campaigns:manage", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List templates.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/templates", "body": null }, "effects": "Reads state through GET /api/messages/templates without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/templates", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "templates.create", "title": "Create template", "description": "Register a WhatsApp message template.", "method": "POST", "path": "/api/messages/templates", "permission": "campaigns:manage", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "language": { "type": "string", "minLength": 1 }, "category": { "type": "string", "enum": [ "marketing", "utility", "authentication", "service" ] }, "sampleBody": { "type": "string", "minLength": 1 } }, "required": [ "name", "sampleBody" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create template.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "name": "example", "sampleBody": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/messages/templates", "body": { "name": "example", "sampleBody": "example" } }, "effects": "May change state through POST /api/messages/templates. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/messages/templates", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "outbound_jobs.list", "title": "List outbound jobs", "description": "List recent outbound WhatsApp delivery jobs.", "method": "GET", "path": "/api/messages/outbound-jobs", "permission": "inbox:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List outbound jobs.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example", "status": "example", "limit": 1 }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/outbound-jobs", "body": null }, "effects": "Reads state through GET /api/messages/outbound-jobs without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/outbound-jobs", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "webhook_events.list", "title": "List webhook events", "description": "List recent WhatsApp webhook intake events.", "method": "GET", "path": "/api/messages/webhook-events", "permission": "inbox:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List webhook events.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example", "status": "example", "limit": 1 }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/webhook-events", "body": null }, "effects": "Reads state through GET /api/messages/webhook-events without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/webhook-events", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.create", "title": "Create campaign", "description": "Create a messaging campaign.", "method": "POST", "path": "/api/messages/campaigns", "permission": "campaigns:manage", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "numberId": { "type": "string", "minLength": 1 }, "templateName": { "type": "string", "minLength": 1 }, "templateLanguage": { "type": "string", "minLength": 1 }, "templateParameters": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "templateParametersText": { "type": "string", "minLength": 1 }, "audienceSource": { "type": "string", "minLength": 1 }, "scheduledAt": { "type": "string", "minLength": 1 }, "recipientsText": { "type": "string", "minLength": 1 }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "phoneNumber": { "type": "string", "minLength": 1 }, "phone": { "type": "string", "minLength": 1 }, "recipientPhone": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "recipientName": { "type": "string", "minLength": 1 } }, "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create campaign.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "name": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/messages/campaigns", "body": { "name": "example" } }, "effects": "May change state through POST /api/messages/campaigns. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/messages/campaigns", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.recipients.list", "title": "List campaign recipients", "description": "List recipients and delivery state for a messaging campaign.", "method": "GET", "path": "/api/messages/campaigns/{campaignId}/recipients", "permission": "campaigns:manage", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "campaignId": { "type": "string", "minLength": 1 } }, "required": [ "campaignId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List campaign recipients.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "campaignId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/campaigns/example/recipients", "body": null }, "effects": "Reads state through GET /api/messages/campaigns/{campaignId}/recipients without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/campaigns/*/recipients", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "automations.list", "title": "List automations", "description": "List messaging automations.", "method": "GET", "path": "/api/messages/automations", "permission": "automations:manage", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List automations.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/automations", "body": null }, "effects": "Reads state through GET /api/messages/automations without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/automations", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "automations.runs.list", "title": "List automation runs", "description": "List recent messaging automation execution runs.", "method": "GET", "path": "/api/messages/automations/runs", "permission": "automations:manage", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "automationId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List automation runs.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example", "automationId": "example", "limit": 1 }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/automations/runs", "body": null }, "effects": "Reads state through GET /api/messages/automations/runs without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/automations/runs", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.launch", "title": "Launch campaign", "description": "Queue a drafted messaging campaign for pending recipients.", "method": "POST", "path": "/api/messages/campaigns/{campaignId}/launch", "permission": "campaigns:manage", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "campaignId": { "type": "string", "minLength": 1 } }, "required": [ "campaignId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Launch campaign.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "campaignId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/messages/campaigns/example/launch", "body": { "campaignId": "example" } }, "effects": "May change state through POST /api/messages/campaigns/{campaignId}/launch. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/messages/campaigns/*/launch", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "automations.create", "title": "Create automation", "description": "Create a messaging automation.", "method": "POST", "path": "/api/messages/automations", "permission": "automations:manage", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "triggerType": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "numberId": { "type": "string", "minLength": 1 }, "definition": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "triggerType" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create automation.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "name": "example", "triggerType": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/messages/automations", "body": { "name": "example", "triggerType": "example" } }, "effects": "May change state through POST /api/messages/automations. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/messages/automations", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "numbers.list", "title": "List numbers", "description": "List messaging phone numbers.", "method": "GET", "path": "/api/messages/numbers", "permission": "numbers:manage", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List numbers.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/numbers", "body": null }, "effects": "Reads state through GET /api/messages/numbers without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/numbers", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "Delete workspace", "description": "Delete an empty, non-default Messages workspace.", "method": "DELETE", "path": "/api/messages/workspaces/{workspaceId}", "permission": "workspace:delete", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete workspace.", "additionalProperties": true }, "readOnly": false, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/messages/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/messages/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/messages/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "contacts.get", "title": "Get contact", "description": "Get one Messages contact.", "method": "GET", "path": "/api/messages/contacts/{contactId}", "permission": "inbox:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "contactId": { "type": "string", "minLength": 1 } }, "required": [ "contactId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get contact.", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "contactId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/contacts/example", "body": null }, "effects": "Reads state through GET /api/messages/contacts/{contactId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/contacts/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "conversations.get", "title": "Get conversation", "description": "Get one Messages conversation.", "method": "GET", "path": "/api/messages/conversations/{conversationId}", "permission": "inbox:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "conversationId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get conversation.", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "conversationId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/conversations/example", "body": null }, "effects": "Reads state through GET /api/messages/conversations/{conversationId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/conversations/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "conversation_messages.list", "title": "List conversation messages", "description": "List message history for one conversation.", "method": "GET", "path": "/api/messages/conversations/{conversationId}/messages", "permission": "inbox:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "conversationId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List conversation messages.", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "conversationId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/conversations/example/messages", "body": null }, "effects": "Reads state through GET /api/messages/conversations/{conversationId}/messages without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/conversations/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "templates.get", "title": "Get template", "description": "Get one Messages template.", "method": "GET", "path": "/api/messages/templates/{templateId}", "permission": "inbox:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "templateId": { "type": "string", "minLength": 1 } }, "required": [ "templateId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get template.", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "templateId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/templates/example", "body": null }, "effects": "Reads state through GET /api/messages/templates/{templateId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/templates/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "campaigns.get", "title": "Get campaign", "description": "Get one Messages campaign.", "method": "GET", "path": "/api/messages/campaigns/{campaignId}", "permission": "inbox:read", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "campaignId": { "type": "string", "minLength": 1 } }, "required": [ "campaignId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get campaign.", "additionalProperties": true }, "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "campaignId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/campaigns/example", "body": null }, "effects": "Reads state through GET /api/messages/campaigns/{campaignId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/campaigns/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "channels.connect", "title": "Connect channel", "description": "Connect a messaging channel to the active Messages workspace by exchanging a provider authorization code. WhatsApp today; the same action serves other channels.", "method": "POST", "path": "/api/messages/channels/connect", "permission": "numbers:manage", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "whatsapp" ] }, "code": { "type": "string", "minLength": 1 }, "accountId": { "type": "string", "minLength": 1 } }, "required": [ "code", "accountId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Connect channel.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "code": "example", "accountId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/messages/channels/connect", "body": { "code": "example", "accountId": "example" } }, "effects": "May change state through POST /api/messages/channels/connect. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/messages/channels/connect", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "messages.semantic_search", "title": "Search messages semantically", "description": "Find workspace-scoped message content by meaning without storing plaintext in the semantic index.", "method": "POST", "path": "/api/messages/semantic-search", "permission": "inbox:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "searchText": { "type": "string", "minLength": 2, "maxLength": 1000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 25 } }, "required": [ "searchText" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Workspace-scoped semantic message matches with decrypted content returned only to the authorized caller.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "searchText": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "POST", "path": "/api/messages/semantic-search", "body": { "searchText": "example" } }, "effects": "Reads state through POST /api/messages/semantic-search without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/messages/semantic-search", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.protection.canary", "title": "Check Messages data protection", "description": "Verify canonical Messages protected fields decrypt under the active D1 application root.", "method": "GET", "path": "/api/messages/privacy/protection/canary", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Messages protection canary result without plaintext or key material.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/privacy/protection/canary", "body": null }, "effects": "Reads state through GET /api/messages/privacy/protection/canary without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/privacy/protection/canary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.export", "title": "Export workspace data", "description": "Export all Messages records for one authorized workspace with protected content decrypted for the requester.", "method": "GET", "path": "/api/messages/privacy/export", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Workspace-scoped Messages data export.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/messages/privacy/export", "body": null }, "effects": "Reads state through GET /api/messages/privacy/export without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/messages/privacy/export", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.delete", "title": "Erase workspace data", "description": "Permanently erase all Messages content in one authorized workspace while retaining its workspace identity.", "method": "DELETE", "path": "/api/messages/privacy", "permission": "workspace:delete", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Workspace-scoped Messages erasure result.", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-messages --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/messages/privacy", "body": null }, "effects": "May change state through DELETE /api/messages/privacy. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/messages/privacy", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 32, "matched_actions": 31, "declared_unserved_actions": [ "GET /api/widget" ], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 1, "configured_exclusions": 3, "configuration_findings": [ "* /api/auth/*: exclusion matches no served route", "* /api/messages/*: exclusion matches no served route", "POST /api/messages/whatsapp/webhook: exclusion matches no served route" ], "notes": [] }, "runtime_contract_audit": { "status": "verified", "actions": 32, "contracts": 32, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/worker.ts" ], "authorization_sources": [ "apps/api/src/worker.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloMessages/topolo.mobile-experience.json", "contract": { "version": "2026-06-29", "status": "approved", "mode": "native_capability", "appId": "app_topolo_messages", "localizationNamespace": "messages", "permissions": [ "inbox:read", "campaigns:manage" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/conversations", "auth": { "audience": "topolo-messages", "scopes": [ "inbox:read", "campaigns:manage" ] }, "routes": [ { "path": "/conversations", "apiPath": "/api/messages/conversations", "title": "Conversations", "titleKey": "messages.InboxRoute.conversations", "template": "record.list", "dataSource": "messages.conversations.list", "detailRoute": "/conversations/:id" }, { "path": "/conversations/:id", "apiPath": "/api/messages/conversations/:id", "title": "Conversations", "titleKey": "messages.InboxRoute.conversations", "template": "record.detail", "dataSource": "messages.conversations.detail" }, { "path": "/contacts", "apiPath": "/api/messages/contacts", "title": "Contacts", "titleKey": "messages.nav.contacts.label", "template": "record.list", "dataSource": "messages.contacts.list", "detailRoute": "/contacts/:id" }, { "path": "/contacts/:id", "apiPath": "/api/messages/contacts/:id", "title": "Contacts", "titleKey": "messages.nav.contacts.label", "template": "record.detail", "dataSource": "messages.contacts.detail" }, { "path": "/campaigns", "apiPath": "/api/messages/campaigns", "title": "Campaigns", "titleKey": "messages.nav.campaigns.label", "template": "record.list", "dataSource": "messages.campaigns.list", "detailRoute": "/campaigns/:id" }, { "path": "/campaigns/:id", "apiPath": "/api/messages/campaigns/:id", "title": "Campaigns", "titleKey": "messages.nav.campaigns.label", "template": "record.detail", "dataSource": "messages.campaigns.detail" }, { "path": "/templates", "apiPath": "/api/messages/templates", "title": "Templates", "titleKey": "messages.nav.templates.label", "template": "record.list", "dataSource": "messages.templates.list", "detailRoute": "/templates/:id" }, { "path": "/templates/:id", "apiPath": "/api/messages/templates/:id", "title": "Templates", "titleKey": "messages.nav.templates.label", "template": "record.detail", "dataSource": "messages.templates.detail" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "ALL", "path": "*", "source_path": "apps/TopoloMessages/apps/api/src/worker.ts" }, { "method": "GET", "path": "/health", "source_path": "apps/TopoloMessages/apps/jobs/src/worker.ts" } ], "ui_routes": [ { "path": "/campaigns/${encodeURIComponent(campaignId)}", "source_path": "apps/TopoloMessages/apps/api/functions/api/messages/campaigns.ts" }, { "path": "/api/widget", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/bootstrap", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/workspaces/{workspaceId}", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/privacy/export", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/privacy", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/privacy/protection/canary", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/semantic-search", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/analytics", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/provider-status", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/conversations", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/contacts", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/contacts/{contactId}", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/conversations/{conversationId}", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/conversations/{conversationId}/messages", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/messages/send", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/campaigns", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/campaigns/{campaignId}", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/templates", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/templates/{templateId}", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/outbound-jobs", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/webhook-events", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/campaigns/{campaignId}/recipients", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/campaigns/{campaignId}/launch", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/automations", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/automations/runs", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/numbers", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/api/messages/channels/connect", "source_path": "apps/TopoloMessages/apps/api/src/topolo.action-contracts.mjs" }, { "path": "/health", "source_path": "apps/TopoloMessages/apps/web/src/App.tsx" }, { "path": "/inbox", "source_path": "apps/TopoloMessages/apps/web/src/App.tsx" }, { "path": "/contacts", "source_path": "apps/TopoloMessages/apps/web/src/App.tsx" }, { "path": "/analytics", "source_path": "apps/TopoloMessages/apps/web/src/App.tsx" }, { "path": "/numbers", "source_path": "apps/TopoloMessages/apps/web/src/App.tsx" }, { "path": "/templates", "source_path": "apps/TopoloMessages/apps/web/src/App.tsx" }, { "path": "/campaigns", "source_path": "apps/TopoloMessages/apps/web/src/App.tsx" }, { "path": "/deliveries", "source_path": "apps/TopoloMessages/apps/web/src/App.tsx" }, { "path": "/automations", "source_path": "apps/TopoloMessages/apps/web/src/App.tsx" }, { "path": "/webhooks", "source_path": "apps/TopoloMessages/apps/web/src/App.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloMessages/apps/web/src/App.tsx" }, { "path": "/settings", "source_path": "apps/TopoloMessages/apps/web/src/App.tsx" }, { "path": "/settings/:section", "source_path": "apps/TopoloMessages/apps/web/src/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "internal/apps/messages", "applications/messages" ], "present_paths": [ "internal/apps/messages", "applications/messages" ], "missing_paths": [], "human_reference": "/systems/topolo-messages", "machine_reference": "/machine/systems/topolo-messages.json", "action_examples": 32, "action_schemas": 32 }, "source_findings": [ { "type": "declared_unserved_actions", "source_path": "apps/TopoloMessages/topolo.app.json", "detail": [ "GET /api/widget" ] }, { "type": "action_coverage_configuration", "source_path": "apps/TopoloMessages/topolo.app.json", "detail": [ "* /api/auth/*: exclusion matches no served route", "* /api/messages/*: exclusion matches no served route", "POST /api/messages/whatsapp/webhook: exclusion matches no served route" ] } ] }, "topolo-nexus": { "id": "topolo-nexus", "name": "Topolo Nexus", "slug": "topolo-nexus", "kind": "application", "visibility": "public", "repo_paths": [ "topolo-platform/services/TopoloNexus" ], "source_revisions": [ { "source_path": "topolo-platform/services/TopoloNexus", "repository": "topolo-platform", "revision": "515376de81efed9734741b2a1d691c8195243073", "ref": "origin/staging" } ], "source_counts": { "source_files": 104, "test_files": 74, "test_cases": 0, "migration_files": 0, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 77, "mobile_contracts": 1, "notifications": 8, "package_manifests": 3, "deployment_configs": 0 }, "manifests": [ { "source_path": "topolo-platform/services/TopoloNexus/topolo.app.json", "service_slug": "topolo-nexus", "name": "topolo-nexus", "app_id": "app_topolo_nexus", "compatibility_date": "2026-04-18", "primary_target": "web", "environments": [ "development", "production", "staging" ], "targets": [ { "name": "web", "kind": "worker", "directory": "apps/dashboard", "main": "src/worker.ts", "worker_name": "topolo-nexus-dashboard", "subdomain": "nexus", "healthcheck_path": null, "variable_names": [], "secret_names": [], "bindings": [] }, { "name": "gateway", "kind": "worker", "directory": "apps/gateway", "main": "src/index.ts", "worker_name": "topolo-nexus-gateway", "subdomain": null, "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": [ "nexus.credential.invalid", "nexus.delivery.failed", "nexus.provider.connection_expiring", "nexus.provider.degraded", "nexus.provider.disconnected", "nexus.provider.recovered", "nexus.usage.threshold_reached", "nexus.webhook.failed" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_nexus", "events": [ { "type": "nexus.credential.invalid", "version": 1, "description": "Nexus persisted an operation after its credential canary found active encrypted material that the current key ring cannot decrypt.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "credential_table", "credential_identity", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "credential_table": { "type": "string", "minLength": 1 }, "credential_identity": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Nexus credential is invalid", "body": "provider_credentials contains a credential Nexus cannot decrypt.", "object_id": "provider_credentials:scope=platform_default provider=openai organization_id=-", "credential_table": "provider_credentials", "credential_identity": "scope=platform_default provider=openai organization_id=-", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://nexus.topolo.app" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^nexus:credential-invalid:" } }, { "type": "nexus.delivery.failed", "version": 1, "description": "Nexus persisted a delivery-failure operation after an authenticated email or WhatsApp provider attempt reached a failed terminal result.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "provider", "app_id", "request_id", "error", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 }, "request_id": { "type": "string", "minLength": 1 }, "error": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Resend delivery failed", "body": "app_topolo_messages could not complete a Resend delivery.", "object_id": "req_delivery_123", "provider": "resend", "app_id": "app_topolo_messages", "request_id": "req_delivery_123", "error": "Provider rejected the message", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://nexus.topolo.app" } ], "dataClassification": "internal", "sensitiveFields": [ "error" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^nexus:delivery-failed:" } }, { "type": "nexus.provider.connection_expiring", "version": 1, "description": "A scheduled Nexus scan found an active persisted provider connection whose token enters the seven-day expiry window.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "provider", "connection_id", "expires_at", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "connection_id": { "type": "string", "minLength": 1 }, "expires_at": { "type": "string", "format": "date-time" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Your LinkedIn connection expires soon", "body": "Reconnect LinkedIn before 27 July 2026 to avoid an interruption.", "object_id": "linkedin_conn_123", "provider": "linkedin", "connection_id": "linkedin_conn_123", "expires_at": "2026-07-27T00:00:00.000Z", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://nexus.topolo.app" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^nexus:connection-expiring:" } }, { "type": "nexus.provider.degraded", "version": 1, "description": "Nexus persisted a provider-health state transition from healthy or unknown to degraded after a real provider attempt failed.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "provider", "status", "error", "latency_ms", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "status": { "const": "degraded" }, "error": { "type": "string" }, "latency_ms": { "type": "integer", "minimum": 0 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "OpenAI degraded", "body": "OpenAI failed its latest Nexus health check.", "object_id": "openai", "provider": "openai", "status": "degraded", "error": "Provider timeout", "latency_ms": 10000, "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://nexus.topolo.app" } ], "dataClassification": "internal", "sensitiveFields": [ "error" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^nexus:provider-health:" } }, { "type": "nexus.provider.disconnected", "version": 1, "description": "Nexus durably changed or removed a provider connection and then persisted the matching notification operation.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "provider", "connection_id", "status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "connection_id": { "type": "string", "minLength": 1 }, "status": { "enum": [ "disconnected", "deauthorized", "deleted" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Instagram disconnected", "body": "The Instagram connection is now disconnected.", "object_id": "instagram_conn_123", "provider": "instagram", "connection_id": "instagram_conn_123", "status": "disconnected", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://nexus.topolo.app" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^nexus:provider-disconnected:" } }, { "type": "nexus.provider.recovered", "version": 1, "description": "Nexus persisted a provider-health state transition from degraded to healthy after a real provider attempt succeeded.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "provider", "status", "error", "latency_ms", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "status": { "const": "healthy" }, "error": { "type": "string" }, "latency_ms": { "type": "integer", "minimum": 0 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "OpenAI recovered", "body": "OpenAI is responding normally again.", "object_id": "openai", "provider": "openai", "status": "healthy", "error": "", "latency_ms": 420, "occurred_at": "2026-07-20T00:05:00.000Z", "cta_url": "https://nexus.topolo.app" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^nexus:provider-health:" } }, { "type": "nexus.usage.threshold_reached", "version": 1, "description": "A persisted usage counter crossed the next configured per-meter threshold and Nexus advanced its durable notification watermark.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "app_id", "meter_id", "meter_key", "consumed_units", "included_units", "threshold_percentage", "period_start", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 }, "meter_id": { "type": "string", "minLength": 1 }, "meter_key": { "type": "string", "minLength": 1 }, "consumed_units": { "type": "integer", "minimum": 0 }, "included_units": { "type": "integer", "minimum": 1 }, "threshold_percentage": { "type": "integer", "minimum": 1 }, "period_start": { "type": "integer", "minimum": 0 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "app_topolo_agent usage reached 80%", "body": "ai_tokens usage is 800 of 1000 included units.", "object_id": "meter_agent_ai", "app_id": "app_topolo_agent", "meter_id": "meter_agent_ai", "meter_key": "ai_tokens", "consumed_units": 800, "included_units": 1000, "threshold_percentage": 80, "period_start": 1784505600000, "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://nexus.topolo.app" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^nexus:usage-threshold:" } }, { "type": "nexus.webhook.failed", "version": 1, "description": "Nexus verified a provider webhook but persisted a failure operation after its authenticated downstream relay failed.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "provider", "request_id", "error", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "request_id": { "type": "string", "minLength": 1 }, "error": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Stripe webhook failed", "body": "Nexus could not relay a verified Stripe webhook.", "object_id": "req_webhook_123", "provider": "stripe", "request_id": "req_webhook_123", "error": "Downstream returned 503", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://nexus.topolo.app" } ], "dataClassification": "internal", "sensitiveFields": [ "error" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^nexus:webhook-failed:" } } ] }, "actions": [ { "name": "widget.get", "title": "Widget Get", "description": "Read GET /api/widget through Nexus.", "method": "GET", "path": "/api/widget", "permission": "dashboard:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Widget Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "organization.get", "title": "Organization Get", "description": "Read GET /api/organization through Nexus.", "method": "GET", "path": "/api/organization", "permission": "organizations:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Organization Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organization", "body": null }, "effects": "Reads state through GET /api/organization without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organization", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organization.provision", "title": "Organization Provision", "description": "Invoke POST /api/organizations/provision through Nexus.", "method": "POST", "path": "/api/organizations/provision", "permission": "organizations:provision", "authorizationMode": "runtime", "allowedServices": [ "topolo-auth" ], "agentContract": { "examples": [ { "organization_id": "org_demo", "name": "Demo Organization", "slug": "demo-organization" } ] }, "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "organization_id": { "type": "string", "minLength": 1 }, "name": { "$ref": "#/properties/organization_id" }, "slug": { "$ref": "#/properties/organization_id" }, "billing_email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] } }, "required": [ "organization_id", "name", "slug" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Organization Provision.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "organization_id": "org_demo", "name": "Demo Organization", "slug": "demo-organization" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/organizations/provision", "body": { "organization_id": "org_demo", "name": "Demo Organization", "slug": "demo-organization" } }, "effects": "May change state through POST /api/organizations/provision. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/organizations/provision", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "audit.list", "title": "Audit List", "description": "Read GET /api/audit through Nexus.", "method": "GET", "path": "/api/audit", "permission": "audit:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 200 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Audit List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "limit": 1 }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/audit", "body": null }, "effects": "Reads state through GET /api/audit without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/audit", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.export", "title": "Privacy Export", "description": "Read GET /api/privacy through Nexus.", "method": "GET", "path": "/api/privacy", "permission": "org:admin", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Privacy Export.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/privacy", "body": null }, "effects": "Reads state through GET /api/privacy without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/privacy", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.delete", "title": "Privacy Delete", "description": "Erase all Nexus-owned data for the authenticated organization and retain only hash-based compliance evidence.", "method": "DELETE", "path": "/api/privacy", "permission": "org:admin", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Privacy Delete.", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/privacy", "body": null }, "effects": "May change state through DELETE /api/privacy. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/privacy", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.list", "title": "Apps List", "description": "Read GET /api/apps through Nexus.", "method": "GET", "path": "/api/apps", "permission": "apps:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Apps List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/apps", "body": null }, "effects": "Reads state through GET /api/apps without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/apps", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.get", "title": "Apps Get", "description": "Read GET /api/apps/{appSlug} through Nexus.", "method": "GET", "path": "/api/apps/{appSlug}", "permission": "apps:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "appSlug": { "type": "string", "minLength": 1 } }, "required": [ "appSlug" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Apps Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "appSlug": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/apps/example", "body": null }, "effects": "Reads state through GET /api/apps/{appSlug} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/apps/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.update", "title": "Apps Update", "description": "Invoke PATCH /api/apps/{appSlug} through Nexus.", "method": "PATCH", "path": "/api/apps/{appSlug}", "permission": "apps:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "appSlug": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "custom_budget_cents": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "appSlug" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Apps Update.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "appSlug": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/apps/example", "body": { "appSlug": "example" } }, "effects": "May change state through PATCH /api/apps/{appSlug}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/apps/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.capabilities.list", "title": "Apps Capabilities List", "description": "Read GET /api/apps/meta/capabilities through Nexus.", "method": "GET", "path": "/api/apps/meta/capabilities", "permission": "apps:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Apps Capabilities List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/apps/meta/capabilities", "body": null }, "effects": "Reads state through GET /api/apps/meta/capabilities without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/apps/meta/capabilities", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.models.list", "title": "Apps Models List", "description": "Read GET /api/apps/meta/models through Nexus.", "method": "GET", "path": "/api/apps/meta/models", "permission": "apps:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Apps Models List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/apps/meta/models", "body": null }, "effects": "Reads state through GET /api/apps/meta/models without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/apps/meta/models", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.overview", "title": "Usage Overview", "description": "Read GET /api/usage/overview through Nexus.", "method": "GET", "path": "/api/usage/overview", "permission": "usage:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "start_date": { "type": "string" }, "end_date": { "$ref": "#/properties/start_date" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage Overview.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "start_date": "example", "end_date": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/usage/overview", "body": null }, "effects": "Reads state through GET /api/usage/overview without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/usage/overview", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.daily", "title": "Usage Daily", "description": "Read GET /api/usage/daily through Nexus.", "method": "GET", "path": "/api/usage/daily", "permission": "usage:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 90 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage Daily.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "days": 1 }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/usage/daily", "body": null }, "effects": "Reads state through GET /api/usage/daily without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/usage/daily", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.by_app", "title": "Usage By App", "description": "Read GET /api/usage/by-app through Nexus.", "method": "GET", "path": "/api/usage/by-app", "permission": "usage:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 90 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage By App.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "days": 1 }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/usage/by-app", "body": null }, "effects": "Reads state through GET /api/usage/by-app without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/usage/by-app", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.by_user", "title": "Usage By User", "description": "Read GET /api/usage/by-user through Nexus.", "method": "GET", "path": "/api/usage/by-user", "permission": "usage:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 90 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500 }, "app_id": { "type": "string" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage By User.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "days": 1, "limit": 1, "app_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/usage/by-user", "body": null }, "effects": "Reads state through GET /api/usage/by-user without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/usage/by-user", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.by_model", "title": "Usage By Model", "description": "Read GET /api/usage/by-model through Nexus.", "method": "GET", "path": "/api/usage/by-model", "permission": "usage:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 90 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage By Model.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "days": 1 }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/usage/by-model", "body": null }, "effects": "Reads state through GET /api/usage/by-model without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/usage/by-model", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.recent", "title": "Usage Recent", "description": "Read GET /api/usage/recent through Nexus.", "method": "GET", "path": "/api/usage/recent", "permission": "usage:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 200 }, "app_id": { "type": "string" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage Recent.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "limit": 1, "app_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/usage/recent", "body": null }, "effects": "Reads state through GET /api/usage/recent without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/usage/recent", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.budget", "title": "Usage Budget", "description": "Read GET /api/usage/budget through Nexus.", "method": "GET", "path": "/api/usage/budget", "permission": "usage:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage Budget.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/usage/budget", "body": null }, "effects": "Reads state through GET /api/usage/budget without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/usage/budget", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.budget.update", "title": "Usage Budget Update", "description": "Invoke PUT /api/usage/budget through Nexus.", "method": "PUT", "path": "/api/usage/budget", "permission": "usage:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "monthly_budget_cents": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "monthly_budget_cents" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage Budget Update.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "monthly_budget_cents": 1 }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/usage/budget", "body": { "monthly_budget_cents": 1 } }, "effects": "May change state through PUT /api/usage/budget. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/usage/budget", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.projection", "title": "Usage Projection", "description": "Read GET /api/usage/projection through Nexus.", "method": "GET", "path": "/api/usage/projection", "permission": "usage:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage Projection.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/usage/projection", "body": null }, "effects": "Reads state through GET /api/usage/projection without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/usage/projection", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.limits.list", "title": "Usage Limits List", "description": "Read GET /api/usage/limits through Nexus.", "method": "GET", "path": "/api/usage/limits", "permission": "usage:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage Limits List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/usage/limits", "body": null }, "effects": "Reads state through GET /api/usage/limits without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/usage/limits", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.limit_options.list", "title": "Usage Limit Options List", "description": "Read GET /api/usage/limits/options through Nexus.", "method": "GET", "path": "/api/usage/limits/options", "permission": "usage:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage Limit Options List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/usage/limits/options", "body": null }, "effects": "Reads state through GET /api/usage/limits/options without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/usage/limits/options", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.limits.update", "title": "Usage Limits Update", "description": "Invoke PUT /api/usage/limits through Nexus.", "method": "PUT", "path": "/api/usage/limits", "permission": "usage:write", "authorizationMode": "runtime", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "scope_type": { "type": "string", "enum": [ "organization", "app", "user", "capability", "use_case", "provider", "model", "platform" ] }, "scope_value": { "type": "string", "minLength": 1 }, "monthly_budget_cents": { "type": "integer", "minimum": 0 }, "hard_limit": { "type": "boolean" }, "is_active": { "type": "boolean" } }, "required": [ "scope_type", "scope_value", "monthly_budget_cents" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage Limits Update.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "scope_type": "organization", "scope_value": "example", "monthly_budget_cents": 1 }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/usage/limits", "body": { "scope_type": "organization", "scope_value": "example", "monthly_budget_cents": 1 } }, "effects": "May change state through PUT /api/usage/limits. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/usage/limits", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.spend.get", "title": "Usage Spend Get", "description": "Read GET /api/usage/spend through Nexus.", "method": "GET", "path": "/api/usage/spend", "permission": "usage:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "start_date": { "type": "string" }, "end_date": { "$ref": "#/properties/start_date" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage Spend Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "start_date": "example", "end_date": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/usage/spend", "body": null }, "effects": "Reads state through GET /api/usage/spend without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/usage/spend", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.events.list", "title": "Usage Events List", "description": "Read GET /api/usage/events through Nexus.", "method": "GET", "path": "/api/usage/events", "permission": "usage:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 200 }, "event_type": { "type": "string" }, "severity": { "$ref": "#/properties/event_type" }, "since": { "$ref": "#/properties/event_type" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage Events List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "limit": 1, "event_type": "example", "severity": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/usage/events", "body": null }, "effects": "Reads state through GET /api/usage/events without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/usage/events", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.key_health.get", "title": "Usage Key Health Get", "description": "Read GET /api/usage/key-health through Nexus.", "method": "GET", "path": "/api/usage/key-health", "permission": "usage:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage Key Health Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/usage/key-health", "body": null }, "effects": "Reads state through GET /api/usage/key-health without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/usage/key-health", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "usage.snapshots.daily", "title": "Usage Snapshots Daily", "description": "Read GET /api/usage/snapshots/daily through Nexus.", "method": "GET", "path": "/api/usage/snapshots/daily", "permission": "usage:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 90 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Usage Snapshots Daily.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "days": 1 }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/usage/snapshots/daily", "body": null }, "effects": "Reads state through GET /api/usage/snapshots/daily without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/usage/snapshots/daily", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.completions.create", "title": "Ai Completions Create", "description": "Invoke POST /api/ai/completions through Nexus.", "method": "POST", "path": "/api/ai/completions", "permission": "ai:invoke", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "anthropic", "google", "xai", "cloudflare" ] }, "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "minItems": 1 }, { "type": "null" } ] }, "tool_call_id": { "$ref": "#/properties/model" }, "tool_calls": { "type": "array", "items": { "$ref": "#/properties/messages/items/properties/content/anyOf/1/items" } }, "name": { "$ref": "#/properties/model" } }, "required": [ "role" ], "additionalProperties": false } }, "prompt": { "$ref": "#/properties/model" }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 32000 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "stream": { "type": "boolean" }, "app_id": { "type": "string", "default": "unknown" }, "use_case": { "type": "string", "enum": [ "chat", "completion", "embedding", "image", "other" ], "default": "chat" }, "response_format": { "type": "object", "properties": { "type": { "type": "string", "const": "json_schema" }, "json_schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "strict": { "type": "boolean" }, "schema": {} }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false }, "tools": { "type": "array", "items": { "$ref": "#/properties/messages/items/properties/content/anyOf/1/items" } } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Ai Completions Create.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "provider": "openai", "model": "example", "messages": [ { "role": "system" } ] }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/completions", "body": { "provider": "openai", "model": "example", "messages": [ { "role": "system" } ] } }, "effects": "May change state through POST /api/ai/completions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/completions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.translations.create", "title": "Ai Translations Create", "description": "Invoke POST /api/ai/translations through Nexus.", "method": "POST", "path": "/api/ai/translations", "permission": "ai:translate", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "anthropic", "google", "xai", "cloudflare" ] }, "model": { "type": "string" }, "source_locale": { "type": "string", "minLength": 2, "maxLength": 16, "default": "en" }, "target_locale": { "type": "string", "minLength": 2, "maxLength": 16 }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80, "default": "common" }, "texts": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 4000 }, "propertyNames": { "minLength": 1 } }, "context": { "type": "string", "maxLength": 2000 }, "app_id": { "type": "string", "default": "unknown" }, "auto_publish": { "type": "boolean", "default": true } }, "required": [ "target_locale", "texts" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Ai Translations Create.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "target_locale": "en-US", "texts": {} }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/translations", "body": { "target_locale": "en-US", "texts": {} } }, "effects": "May change state through POST /api/ai/translations. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/translations", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.embeddings.create", "title": "Ai Embeddings Create", "description": "Invoke POST /api/ai/embeddings through Nexus.", "method": "POST", "path": "/api/ai/embeddings", "permission": "ai:invoke", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "provider": { "type": "string", "const": "cloudflare" }, "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "$ref": "#/properties/input/anyOf/0" }, "minItems": 1, "maxItems": 64 } ] }, "app_id": { "type": "string", "default": "unknown" } }, "required": [ "input" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Ai Embeddings Create.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "input": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/embeddings", "body": { "input": "example" } }, "effects": "May change state through POST /api/ai/embeddings. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/embeddings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.markdown.create", "title": "Ai Markdown Create", "description": "Invoke POST /api/ai/markdown through Nexus.", "method": "POST", "path": "/api/ai/markdown", "permission": "ai:invoke", "agentContract": { "examples": [ { "filename": "brief.txt", "data_base64": "SGVsbG8gVG9wb2xv" } ] }, "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "provider": { "type": "string", "const": "cloudflare" }, "filename": { "type": "string", "minLength": 1 }, "data_base64": { "$ref": "#/properties/filename" }, "mime_type": { "type": "string" }, "app_id": { "type": "string", "default": "unknown" } }, "required": [ "filename", "data_base64" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Ai Markdown Create.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "filename": "brief.txt", "data_base64": "SGVsbG8gVG9wb2xv" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/markdown", "body": { "filename": "brief.txt", "data_base64": "SGVsbG8gVG9wb2xv" } }, "effects": "May change state through POST /api/ai/markdown. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/markdown", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.image.describe", "title": "Ai Image Describe", "description": "Invoke POST /api/ai/image/describe through Nexus.", "method": "POST", "path": "/api/ai/image/describe", "permission": "ai:invoke", "agentContract": { "examples": [ { "filename": "campaign.png", "data_base64": "aW1hZ2U=" } ] }, "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "provider": { "type": "string", "const": "cloudflare" }, "model": { "type": "string" }, "filename": { "type": "string", "minLength": 1 }, "data_base64": { "$ref": "#/properties/filename" }, "mime_type": { "$ref": "#/properties/model" }, "prompt": { "$ref": "#/properties/filename" }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 2048 }, "app_id": { "type": "string", "default": "unknown" } }, "required": [ "filename", "data_base64" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Ai Image Describe.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "filename": "campaign.png", "data_base64": "aW1hZ2U=" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/image/describe", "body": { "filename": "campaign.png", "data_base64": "aW1hZ2U=" } }, "effects": "May change state through POST /api/ai/image/describe. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/image/describe", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.autorag.search", "title": "Ai Autorag Search", "description": "Invoke POST /api/ai/autorag/search through Nexus.", "method": "POST", "path": "/api/ai/autorag/search", "permission": "ai:invoke", "agentContract": { "examples": [ { "instance": "topoloone-auto-rag", "query": "How do refunds work?" } ] }, "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "provider": { "type": "string", "const": "cloudflare" }, "instance": { "type": "string", "minLength": 1 }, "query": { "$ref": "#/properties/instance" }, "max_num_results": { "type": "integer", "minimum": 1, "maximum": 20 }, "rewrite_query": { "type": "boolean" }, "ranking_options": { "type": "object", "properties": { "score_threshold": { "type": "number", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, "app_id": { "type": "string", "default": "unknown" } }, "required": [ "instance", "query" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Ai Autorag Search.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "instance": "topoloone-auto-rag", "query": "How do refunds work?" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/autorag/search", "body": { "instance": "topoloone-auto-rag", "query": "How do refunds work?" } }, "effects": "May change state through POST /api/ai/autorag/search. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/autorag/search", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.transcriptions.create", "title": "Ai Transcriptions Create", "description": "Invoke POST /api/ai/transcriptions through Nexus.", "method": "POST", "path": "/api/ai/transcriptions", "permission": "ai:invoke", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "provider": { "type": "string", "const": "cloudflare" }, "model": { "type": "string" }, "audioDataUrl": { "type": "string", "minLength": 1 }, "audioBase64": { "$ref": "#/properties/audioDataUrl" }, "mime_type": { "$ref": "#/properties/model" }, "language": { "type": "string", "minLength": 2, "maxLength": 8 }, "initial_prompt": { "type": "string", "maxLength": 400 }, "duration_ms": { "type": "integer", "minimum": 0 }, "app_id": { "type": "string", "default": "unknown" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Ai Transcriptions Create.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "provider": "cloudflare", "model": "example", "audioDataUrl": "https://example.com" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/transcriptions", "body": { "provider": "cloudflare", "model": "example", "audioDataUrl": "https://example.com" } }, "effects": "May change state through POST /api/ai/transcriptions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/transcriptions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.generations.create", "title": "Ai Generations Create", "description": "Invoke POST /api/ai/generations through Nexus.", "method": "POST", "path": "/api/ai/generations", "permission": "ai:invoke", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "google", "xai", "cloudflare" ] }, "model": { "type": "string" }, "operation": { "type": "string", "enum": [ "image.generate", "video.generate", "video.poll", "audio.speech", "music.generate" ] }, "prompt": { "$ref": "#/properties/model" }, "negative_prompt": { "$ref": "#/properties/model" }, "candidate_count": { "type": "integer", "minimum": 1, "maximum": 4 }, "aspect_ratio": { "$ref": "#/properties/model" }, "duration_seconds": { "type": "integer", "minimum": 1, "maximum": 30 }, "resolution": { "$ref": "#/properties/model" }, "quality": { "$ref": "#/properties/model" }, "width": { "type": "integer", "minimum": 64, "maximum": 4096 }, "height": { "type": "integer", "minimum": 64, "maximum": 4096 }, "seed": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "generate_audio": { "type": "boolean" }, "lyrics": { "type": "string", "minLength": 1, "maxLength": 3500 }, "lyrics_optimizer": { "type": "boolean" }, "is_instrumental": { "type": "boolean" }, "format": { "$ref": "#/properties/model" }, "sample_rate": { "type": "integer" }, "bitrate": { "type": "integer" }, "voice_id": { "$ref": "#/properties/model" }, "speaker": { "$ref": "#/properties/model" }, "speed": { "type": "number", "minimum": 0.5, "maximum": 2 }, "volume": { "type": "number", "minimum": 0, "maximum": 10 }, "pitch": { "type": "integer", "minimum": -12, "maximum": 12 }, "emotion": { "$ref": "#/properties/model" }, "external_job_id": { "$ref": "#/properties/model" }, "source_asset": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1 }, "mime_type": { "$ref": "#/properties/model" } }, "required": [ "url" ], "additionalProperties": false }, "app_id": { "type": "string", "default": "unknown" } }, "required": [ "operation" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Ai Generations Create.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "operation": "image.generate" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/ai/generations", "body": { "operation": "image.generate" } }, "effects": "May change state through POST /api/ai/generations. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/ai/generations", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.models.list", "title": "Ai Models List", "description": "Read GET /api/ai/models through Nexus.", "method": "GET", "path": "/api/ai/models", "permission": "ai:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Ai Models List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/models", "body": null }, "effects": "Reads state through GET /api/ai/models without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/models", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ai.provider_health.get", "title": "Ai Provider Health Get", "description": "Read GET /api/ai/health/{provider} through Nexus.", "method": "GET", "path": "/api/ai/health/{provider}", "permission": "ai:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1 } }, "required": [ "provider" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Ai Provider Health Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "provider": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ai/health/example", "body": null }, "effects": "Reads state through GET /api/ai/health/{provider} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ai/health/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "provider_credentials.list", "title": "Provider Credentials List", "description": "Read GET /api/provider-credentials through Nexus.", "method": "GET", "path": "/api/provider-credentials", "permission": "provider_credentials:read", "authorizationMode": "runtime", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Provider Credentials List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/provider-credentials", "body": null }, "effects": "Reads state through GET /api/provider-credentials without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/provider-credentials", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "provider_credentials.upsert", "title": "Provider Credentials Upsert", "description": "Invoke PUT /api/provider-credentials/{provider} through Nexus.", "method": "PUT", "path": "/api/provider-credentials/{provider}", "permission": "provider_credentials:write", "authorizationMode": "runtime", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1 }, "secret": { "type": "string", "minLength": 10 } }, "required": [ "provider", "secret" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Provider Credentials Upsert.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "provider": "example", "secret": "examplexxx" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/provider-credentials/example", "body": { "provider": "example", "secret": "examplexxx" } }, "effects": "May change state through PUT /api/provider-credentials/{provider}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/provider-credentials/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "provider_credentials.update", "title": "Provider Credentials Update", "description": "Invoke PATCH /api/provider-credentials/{provider} through Nexus.", "method": "PATCH", "path": "/api/provider-credentials/{provider}", "permission": "provider_credentials:write", "authorizationMode": "runtime", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1 }, "is_active": { "type": "boolean" } }, "required": [ "provider", "is_active" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Provider Credentials Update.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "provider": "example", "is_active": true }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/provider-credentials/example", "body": { "provider": "example", "is_active": true } }, "effects": "May change state through PATCH /api/provider-credentials/{provider}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/provider-credentials/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "preferences.list", "title": "Preferences List", "description": "Read GET /api/preferences through Nexus.", "method": "GET", "path": "/api/preferences", "permission": "preferences:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Preferences List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/preferences", "body": null }, "effects": "Reads state through GET /api/preferences without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/preferences", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "preferences.get", "title": "Preferences Get", "description": "Read GET /api/preferences/{useCase} through Nexus.", "method": "GET", "path": "/api/preferences/{useCase}", "permission": "preferences:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "useCase": { "type": "string", "minLength": 1 } }, "required": [ "useCase" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Preferences Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "useCase": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/preferences/example", "body": null }, "effects": "Reads state through GET /api/preferences/{useCase} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/preferences/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "preferences.set", "title": "Preferences Set", "description": "Invoke PUT /api/preferences/{useCase} through Nexus.", "method": "PUT", "path": "/api/preferences/{useCase}", "permission": "preferences:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "useCase": { "type": "string", "minLength": 1 }, "preferred_provider": { "type": "string", "enum": [ "openai", "anthropic", "google", "xai", "cloudflare" ] }, "preferred_model": { "type": "string" }, "fallback_provider": { "anyOf": [ { "$ref": "#/properties/preferred_provider" }, { "type": "null" } ] }, "fallback_model": { "type": [ "string", "null" ] }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 32000 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 } }, "required": [ "useCase", "preferred_provider", "preferred_model" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Preferences Set.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "useCase": "example", "preferred_provider": "openai", "preferred_model": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/preferences/example", "body": { "useCase": "example", "preferred_provider": "openai", "preferred_model": "example" } }, "effects": "May change state through PUT /api/preferences/{useCase}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/preferences/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "preferences.delete", "title": "Preferences Delete", "description": "Invoke DELETE /api/preferences/{useCase} through Nexus.", "method": "DELETE", "path": "/api/preferences/{useCase}", "permission": "preferences:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "useCase": { "type": "string", "minLength": 1 } }, "required": [ "useCase" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Preferences Delete.", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "useCase": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/preferences/example", "body": null }, "effects": "May change state through DELETE /api/preferences/{useCase}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/preferences/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "preferences.available_models.list", "title": "Preferences Available Models List", "description": "Read GET /api/preferences/available/models through Nexus.", "method": "GET", "path": "/api/preferences/available/models", "permission": "preferences:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Preferences Available Models List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/preferences/available/models", "body": null }, "effects": "Reads state through GET /api/preferences/available/models without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/preferences/available/models", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "models.governance.get", "title": "Models Governance Get", "description": "Read GET /api/models/governance through Nexus.", "method": "GET", "path": "/api/models/governance", "permission": "models:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Models Governance Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/models/governance", "body": null }, "effects": "Reads state through GET /api/models/governance without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/models/governance", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "models.sync", "title": "Models Sync", "description": "Invoke POST /api/models/sync through Nexus.", "method": "POST", "path": "/api/models/sync", "permission": "models:write", "authorizationMode": "runtime", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "provider": { "type": "string" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Models Sync.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "provider": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/models/sync", "body": { "provider": "example" } }, "effects": "May change state through POST /api/models/sync. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/models/sync", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "email.connections.list", "title": "Email Connections List", "description": "Read GET /api/email/connections through Nexus.", "method": "GET", "path": "/api/email/connections", "permission": "email:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Email Connections List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/email/connections", "body": null }, "effects": "Reads state through GET /api/email/connections without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/email/connections", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "email.connections.create", "title": "Email Connections Create", "description": "Invoke POST /api/email/connections through Nexus.", "method": "POST", "path": "/api/email/connections", "permission": "email:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "resend", "cloudflare_email" ] }, "connection_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "sending_domain": { "type": "string", "minLength": 3, "maxLength": 255 }, "default_from_name": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "default_reply_to_email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] } }, "required": [ "provider", "connection_name", "sending_domain" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Email Connections Create.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "provider": "resend", "connection_name": "example", "sending_domain": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/email/connections", "body": { "provider": "resend", "connection_name": "example", "sending_domain": "example" } }, "effects": "May change state through POST /api/email/connections. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/email/connections", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "email.connections.update", "title": "Email Connections Update", "description": "Invoke PATCH /api/email/connections/{id} through Nexus.", "method": "PATCH", "path": "/api/email/connections/{id}", "permission": "email:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "connection_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "sending_domain": { "type": "string", "minLength": 3, "maxLength": 255 }, "default_from_name": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "default_reply_to_email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "is_active": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Email Connections Update.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/email/connections/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PATCH /api/email/connections/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/email/connections/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "email.profiles.list", "title": "Email Profiles List", "description": "Read GET /api/email/profiles through Nexus.", "method": "GET", "path": "/api/email/profiles", "permission": "email:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "app_id": { "type": "string" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Email Profiles List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "app_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/email/profiles", "body": null }, "effects": "Reads state through GET /api/email/profiles without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/email/profiles", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "email.profiles.create", "title": "Email Profiles Create", "description": "Invoke POST /api/email/profiles through Nexus.", "method": "POST", "path": "/api/email/profiles", "permission": "email:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "connection_id": { "type": "string", "minLength": 1 }, "profile_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "from_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "from_email": { "type": "string", "format": "email" }, "reply_to_email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "app_id": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "is_default": { "type": "boolean" } }, "required": [ "connection_id", "profile_name", "from_name", "from_email" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Email Profiles Create.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "connection_id": "00000000-0000-4000-8000-000000000000", "profile_name": "example", "from_name": "example", "from_email": "user@example.com" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/email/profiles", "body": { "connection_id": "00000000-0000-4000-8000-000000000000", "profile_name": "example", "from_name": "example", "from_email": "user@example.com" } }, "effects": "May change state through POST /api/email/profiles. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/email/profiles", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "email.profiles.update", "title": "Email Profiles Update", "description": "Invoke PATCH /api/email/profiles/{id} through Nexus.", "method": "PATCH", "path": "/api/email/profiles/{id}", "permission": "email:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "profile_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "from_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "from_email": { "type": "string", "format": "email" }, "reply_to_email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "app_id": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "is_default": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Email Profiles Update.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/email/profiles/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PATCH /api/email/profiles/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/email/profiles/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "email.send", "title": "Email Send", "description": "Invoke POST /api/email/send through Nexus.", "method": "POST", "path": "/api/email/send", "permission": "email:send", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "profile_id": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "enum": [ "resend", "cloudflare_email" ] }, "from": { "$ref": "#/properties/profile_id" }, "to": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1 } ] }, "subject": { "type": "string", "minLength": 1, "maxLength": 998 }, "html": { "type": "string" }, "text": { "$ref": "#/properties/html" }, "reply_to": { "$ref": "#/properties/html" }, "cc": { "type": "array", "items": { "type": "string", "format": "email" } }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "$ref": "#/properties/profile_id" }, "value": { "$ref": "#/properties/profile_id" } }, "required": [ "name", "value" ], "additionalProperties": false } }, "message_stream": { "$ref": "#/properties/html" }, "app_id": { "$ref": "#/properties/html" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "$ref": "#/properties/profile_id" }, "content_type": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "filename", "content" ], "additionalProperties": false }, "maxItems": 20 } }, "required": [ "to", "subject" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Email Send.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "to": "user@example.com", "subject": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/email/send", "body": { "to": "user@example.com", "subject": "example" } }, "effects": "May change state through POST /api/email/send. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/email/send", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "whatsapp.send", "title": "Whatsapp Send", "description": "Send a WhatsApp message via the org's connection through Nexus.", "method": "POST", "path": "/api/whatsapp/send", "permission": "whatsapp:send", "authorizationMode": "runtime", "allowedServices": [ "topolo-notify", "topolo-messages-dispatch" ], "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "to": { "type": "string", "minLength": 5, "maxLength": 40 }, "connection_id": { "type": "string" }, "phone_number_id": { "$ref": "#/properties/connection_id" }, "app_id": { "$ref": "#/properties/connection_id" }, "type": { "type": "string", "enum": [ "text", "template" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 4096 }, "preview_url": { "type": "boolean" }, "template": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 2, "maxLength": 20 }, "components": { "type": "array", "items": {} } }, "required": [ "name", "language" ], "additionalProperties": false } }, "required": [ "to" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Whatsapp Send.", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "to": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/whatsapp/send", "body": { "to": "example" } }, "effects": "May change state through POST /api/whatsapp/send. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/whatsapp/send", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "payments.stripe.invoke", "title": "Payments Stripe Invoke", "description": "Invoke POST /api/payments/stripe through Nexus.", "method": "POST", "path": "/api/payments/stripe", "permission": "payments:invoke", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "checkout.sessions.create", "checkout.sessions.retrieve", "checkout.sessions.expire", "prices.create", "products.create", "subscription_items.create", "subscription_items.update", "subscription_items.delete", "subscription_items.create_usage_record", "payment_intents.create", "payment_intents.retrieve", "payment_intents.cancel", "refunds.create", "billing_portal.sessions.create", "subscriptions.retrieve", "subscriptions.update", "invoices.create_preview", "subscriptions.create", "setup_intents.create", "customers.create", "customers.retrieve", "accounts.create", "accounts.retrieve", "accounts.update", "account_links.create", "login_links.create" ] }, "params": { "type": "object", "additionalProperties": {} } }, "required": [ "operation", "params" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Payments Stripe Invoke.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "operation": "checkout.sessions.create", "params": {} }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/payments/stripe", "body": { "operation": "checkout.sessions.create", "params": {} } }, "effects": "May change state through POST /api/payments/stripe. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/payments/stripe", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "billing.overview.get", "title": "Billing Overview Get", "description": "Read GET /api/billing/overview through Nexus.", "method": "GET", "path": "/api/billing/overview", "permission": "billing:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Billing Overview Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/billing/overview", "body": null }, "effects": "Reads state through GET /api/billing/overview without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/billing/overview", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "billing.spend_caps.list", "title": "Billing Spend Caps List", "description": "Read GET /api/billing/spend-caps through Nexus.", "method": "GET", "path": "/api/billing/spend-caps", "permission": "billing:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Billing Spend Caps List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/billing/spend-caps", "body": null }, "effects": "Reads state through GET /api/billing/spend-caps without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/billing/spend-caps", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "billing.spend_caps.upsert", "title": "Billing Spend Caps Upsert", "description": "Invoke POST /api/billing/spend-caps through Nexus.", "method": "POST", "path": "/api/billing/spend-caps", "permission": "billing:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "scopeType": { "type": "string", "enum": [ "organization", "user" ] }, "scopeValue": { "type": [ "string", "null" ] }, "monthlyCapCents": { "type": "number", "minimum": 0 }, "capMode": { "type": "string", "enum": [ "soft", "hard" ] }, "isActive": { "type": "boolean" }, "notifyThresholds": { "type": "array", "items": { "type": "number" } } }, "required": [ "scopeType", "monthlyCapCents" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Billing Spend Caps Upsert.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "scopeType": "organization", "monthlyCapCents": 1 }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/billing/spend-caps", "body": { "scopeType": "organization", "monthlyCapCents": 1 } }, "effects": "May change state through POST /api/billing/spend-caps. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/billing/spend-caps", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "billing.spend_caps.delete", "title": "Billing Spend Caps Delete", "description": "Invoke DELETE /api/billing/spend-caps/{id} through Nexus.", "method": "DELETE", "path": "/api/billing/spend-caps/{id}", "permission": "billing:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Billing Spend Caps Delete.", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/billing/spend-caps/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/billing/spend-caps/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/billing/spend-caps/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "billing.byok_fee.update", "title": "Billing Byok Fee Update", "description": "Invoke POST /api/billing/byok-fee through Nexus.", "method": "POST", "path": "/api/billing/byok-fee", "permission": "billing:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "serviceFeeBps": { "type": "number", "minimum": 0, "maximum": 10000 } }, "required": [ "serviceFeeBps" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Billing Byok Fee Update.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "serviceFeeBps": 1 }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/billing/byok-fee", "body": { "serviceFeeBps": 1 } }, "effects": "May change state through POST /api/billing/byok-fee. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/billing/byok-fee", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "billing.meters.list", "title": "Billing Meters List", "description": "Read GET /api/billing/meters through Nexus.", "method": "GET", "path": "/api/billing/meters", "permission": "billing:read", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Billing Meters List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/billing/meters", "body": null }, "effects": "Reads state through GET /api/billing/meters without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/billing/meters", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "billing.meter_settings.upsert", "title": "Billing Meter Settings Upsert", "description": "Invoke POST /api/billing/meter-settings through Nexus.", "method": "POST", "path": "/api/billing/meter-settings", "permission": "billing:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "meterId": { "type": "string", "minLength": 1 }, "capMode": { "type": "string", "enum": [ "soft", "hard", "hybrid" ] }, "hardCapUnits": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "notifyThresholds": { "type": "array", "items": { "type": "number" } } }, "required": [ "meterId", "capMode" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Billing Meter Settings Upsert.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "meterId": "example", "capMode": "soft" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/billing/meter-settings", "body": { "meterId": "example", "capMode": "soft" } }, "effects": "May change state through POST /api/billing/meter-settings. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/billing/meter-settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "turnstile.verify", "title": "Turnstile Verify", "description": "Invoke POST /platform/turnstile/verify through Nexus.", "method": "POST", "path": "/platform/turnstile/verify", "permission": "turnstile:verify", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "token": { "type": "string" }, "ip": { "type": [ "string", "null" ] }, "appId": { "type": [ "string", "null" ] } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Turnstile Verify.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "token": "example", "ip": "example", "appId": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/platform/turnstile/verify", "body": { "token": "example", "ip": "example", "appId": "example" } }, "effects": "May change state through POST /platform/turnstile/verify. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /platform/turnstile/verify", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ratelimit.check", "title": "Ratelimit Check", "description": "Invoke POST /platform/ratelimit/check through Nexus.", "method": "POST", "path": "/platform/ratelimit/check", "permission": "ratelimit:check", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 200 }, "limit": { "type": "number", "minimum": 1, "maximum": 100000 }, "windowSeconds": { "type": "number", "minimum": 1, "maximum": 3600 }, "cost": { "type": "number", "minimum": 1, "maximum": 1000 }, "appId": { "type": [ "string", "null" ] } }, "required": [ "key", "limit", "windowSeconds" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Ratelimit Check.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "key": "example", "limit": 1, "windowSeconds": 1 }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/platform/ratelimit/check", "body": { "key": "example", "limit": 1, "windowSeconds": 1 } }, "effects": "May change state through POST /platform/ratelimit/check. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /platform/ratelimit/check", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "integrations.connections.list", "title": "Integrations Connections List", "description": "Invoke POST /platform/integrations/connections/list through Nexus.", "method": "POST", "path": "/platform/integrations/connections/list", "permission": "integrations:read", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "app_resource_type": { "$ref": "#/properties/app_id" }, "app_resource_id": { "$ref": "#/properties/app_id" }, "provider": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z0-9][a-z0-9_.:-]*$" }, "include_inactive": { "type": "boolean", "default": false } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Integrations Connections List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "app_id": "00000000-0000-4000-8000-000000000000", "app_resource_type": "example", "app_resource_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/platform/integrations/connections/list", "body": { "app_id": "00000000-0000-4000-8000-000000000000", "app_resource_type": "example", "app_resource_id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /platform/integrations/connections/list. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /platform/integrations/connections/list", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "integrations.connections.upsert", "title": "Integrations Connections Upsert", "description": "Invoke POST /platform/integrations/connections/upsert through Nexus.", "method": "POST", "path": "/platform/integrations/connections/upsert", "permission": "integrations:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "connection_id": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9._:@+-]+$" }, "app_resource_type": { "type": "string", "minLength": 1, "default": "brand" }, "app_resource_id": { "$ref": "#/properties/app_id" }, "connected_by_user_id": { "type": [ "string", "null" ] }, "provider": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z0-9][a-z0-9_.:-]*$" }, "provider_user_id": { "$ref": "#/properties/app_id" }, "provider_username": { "type": [ "string", "null" ] }, "provider_display_name": { "type": [ "string", "null" ] }, "provider_avatar_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "provider_profile_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "access_token": { "type": [ "string", "null" ] }, "refresh_token": { "type": [ "string", "null" ] }, "credential_payload": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "token_expires_at": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "disconnected", "deauthorized", "deleted", "error" ], "default": "active" }, "reactivate": { "type": "boolean", "default": false }, "metadata": { "$ref": "#/properties/credential_payload/anyOf/0", "default": {} }, "last_error": { "type": [ "string", "null" ] } }, "required": [ "connection_id" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Integrations Connections Upsert.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "connection_id": "2026-01-01" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/platform/integrations/connections/upsert", "body": { "connection_id": "2026-01-01" } }, "effects": "May change state through POST /platform/integrations/connections/upsert. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /platform/integrations/connections/upsert", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "integrations.connections.changes", "title": "Integrations Connections Change Feed", "description": "Poll the organization-scoped connection status change feed forward from a cursor, so an app learns about a disconnect before an action fails.", "method": "POST", "path": "/platform/integrations/connections/changes", "permission": "integrations:read", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "after_seq": { "type": "integer", "minimum": 0, "default": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Integrations Connections Changes.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "app_id": "00000000-0000-4000-8000-000000000000", "after_seq": 0, "limit": 100 }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/platform/integrations/connections/changes", "body": { "app_id": "00000000-0000-4000-8000-000000000000", "after_seq": 0, "limit": 100 } }, "effects": "May change state through POST /platform/integrations/connections/changes. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /platform/integrations/connections/changes", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "integrations.connections.disconnect", "title": "Integrations Connections Disconnect", "description": "Invoke POST /platform/integrations/connections/disconnect through Nexus.", "method": "POST", "path": "/platform/integrations/connections/disconnect", "permission": "integrations:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "connection_id": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9._:@+-]+$" }, "mode": { "type": "string", "enum": [ "disconnect", "deauthorize", "delete" ], "default": "disconnect" }, "last_error": { "type": [ "string", "null" ] } }, "required": [ "connection_id" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Integrations Connections Disconnect.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "connection_id": "2026-01-01" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/platform/integrations/connections/disconnect", "body": { "connection_id": "2026-01-01" } }, "effects": "May change state through POST /platform/integrations/connections/disconnect. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /platform/integrations/connections/disconnect", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "integrations.app_credentials.health", "title": "Integrations App Credentials Health", "description": "Read GET /platform/integrations/app-credentials/health through Nexus.", "method": "GET", "path": "/platform/integrations/app-credentials/health", "permission": "integrations:admin", "authorizationMode": "runtime", "allowedServices": [ "topolo-platform-mcp" ], "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Integrations App Credentials Health.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/platform/integrations/app-credentials/health", "body": null }, "effects": "Reads state through GET /platform/integrations/app-credentials/health without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /platform/integrations/app-credentials/health", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "integrations.app_credentials.list", "title": "Integrations App Credentials List", "description": "Invoke POST /platform/integrations/app-credentials/list through Nexus.", "method": "POST", "path": "/platform/integrations/app-credentials/list", "permission": "integrations:admin", "authorizationMode": "runtime", "allowedServices": [ "topolo-platform-mcp" ], "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z0-9][a-z0-9_.:-]*$" }, "environment": { "$ref": "#/properties/app_id" }, "include_inactive": { "type": "boolean", "default": false } }, "required": [ "app_id" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Integrations App Credentials List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "app_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/platform/integrations/app-credentials/list", "body": { "app_id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /platform/integrations/app-credentials/list. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /platform/integrations/app-credentials/list", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "integrations.app_credentials.upsert", "title": "Integrations App Credentials Upsert", "description": "Invoke POST /platform/integrations/app-credentials/upsert through Nexus.", "method": "POST", "path": "/platform/integrations/app-credentials/upsert", "permission": "integrations:admin", "authorizationMode": "runtime", "allowedServices": [ "topolo-platform-mcp" ], "agentContract": { "examples": [ { "app_id": "app_topolo_campaigns", "provider": "facebook", "client_id": "demo-client-id", "client_secret": "demo-client-secret" } ] }, "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z0-9][a-z0-9_.:-]*$" }, "environment": { "type": "string", "minLength": 1, "default": "production" }, "credential_name": { "$ref": "#/properties/app_id" }, "client_id": { "$ref": "#/properties/app_id" }, "client_secret": { "$ref": "#/properties/app_id" }, "scopes": { "type": "array", "items": { "$ref": "#/properties/app_id" }, "default": [] }, "authorization_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "token_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "redirect_uri": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} }, "is_active": { "type": "boolean", "default": true } }, "required": [ "app_id", "provider", "client_id", "client_secret" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Integrations App Credentials Upsert.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "app_id": "app_topolo_campaigns", "provider": "facebook", "client_id": "demo-client-id", "client_secret": "demo-client-secret" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/platform/integrations/app-credentials/upsert", "body": { "app_id": "app_topolo_campaigns", "provider": "facebook", "client_id": "demo-client-id", "client_secret": "demo-client-secret" } }, "effects": "May change state through POST /platform/integrations/app-credentials/upsert. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /platform/integrations/app-credentials/upsert", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "youtube.channel_profile.get", "title": "Youtube Channel Profile Get", "description": "Invoke POST /platform/youtube/channels/profile through Nexus.", "method": "POST", "path": "/platform/youtube/channels/profile", "permission": "youtube:read", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1 }, "app_id": { "$ref": "#/properties/access_token" } }, "required": [ "access_token" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Youtube Channel Profile Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "access_token": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/platform/youtube/channels/profile", "body": { "access_token": "example" } }, "effects": "May change state through POST /platform/youtube/channels/profile. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /platform/youtube/channels/profile", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "youtube.videos.publish", "title": "Youtube Videos Publish", "description": "Invoke POST /platform/youtube/videos/upload through Nexus.", "method": "POST", "path": "/platform/youtube/videos/upload", "permission": "youtube:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1 }, "video_url": { "type": "string", "format": "uri" }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 5000 }, "privacy_status": { "type": "string", "enum": [ "private", "unlisted", "public" ], "default": "private" }, "app_id": { "$ref": "#/properties/access_token" }, "brand_id": { "$ref": "#/properties/app_id" }, "post_id": { "$ref": "#/properties/app_id" } }, "required": [ "access_token", "video_url", "title" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Youtube Videos Publish.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "access_token": "example", "video_url": "https://example.com", "title": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/platform/youtube/videos/upload", "body": { "access_token": "example", "video_url": "https://example.com", "title": "example" } }, "effects": "May change state through POST /platform/youtube/videos/upload. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /platform/youtube/videos/upload", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "platform_usage.events.create", "title": "Platform Usage Events Create", "description": "Invoke POST /platform/usage/events through Nexus.", "method": "POST", "path": "/platform/usage/events", "permission": "usage:write", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "appId": { "$ref": "#/properties/app_id" }, "meter_key": { "type": "string", "minLength": 1, "maxLength": 80 }, "meterKey": { "type": "string", "minLength": 1, "maxLength": 80 }, "event_name": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventName": { "type": "string", "minLength": 1, "maxLength": 160 }, "units": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000, "default": 1 }, "user_id": { "type": [ "string", "null" ] }, "userId": { "type": [ "string", "null" ] }, "request_id": { "type": [ "string", "null" ] }, "requestId": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": {} } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Platform Usage Events Create.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "app_id": "00000000-0000-4000-8000-000000000000", "appId": "example", "meter_key": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/platform/usage/events", "body": { "app_id": "00000000-0000-4000-8000-000000000000", "appId": "example", "meter_key": "example" } }, "effects": "May change state through POST /platform/usage/events. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /platform/usage/events", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "platform_usage.turnstile.get", "title": "Platform Usage Turnstile Get", "description": "Read GET /platform/usage/turnstile through Nexus.", "method": "GET", "path": "/platform/usage/turnstile", "permission": "usage:read", "authorizationMode": "runtime", "readOnly": true, "target": "gateway", "inputSchema": { "type": "object", "properties": { "orgId": { "type": "string" }, "start": { "$ref": "#/properties/orgId" }, "end": { "$ref": "#/properties/orgId" }, "appId": { "$ref": "#/properties/orgId" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Platform Usage Turnstile Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "orgId": "example", "start": "example", "end": "example" }, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/platform/usage/turnstile", "body": null }, "effects": "Reads state through GET /platform/usage/turnstile without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /platform/usage/turnstile", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "platform_usage.meter_settings.backfill", "title": "Platform Usage Meter Settings Backfill", "description": "Invoke POST /platform/usage/meter-settings/backfill through Nexus.", "method": "POST", "path": "/platform/usage/meter-settings/backfill", "permission": "usage:admin", "authorizationMode": "runtime", "readOnly": false, "target": "gateway", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "outputSchema": { "type": "object", "description": "Response returned by Platform Usage Meter Settings Backfill.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-nexus --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/platform/usage/meter-settings/backfill", "body": {} }, "effects": "May change state through POST /platform/usage/meter-settings/backfill. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /platform/usage/meter-settings/backfill", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 102, "matched_actions": 77, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [ { "key": "POST /internal/platform/encryption/master-key/rewrap", "method": "POST", "path": "/internal/platform/encryption/master-key/rewrap", "source": "apps/gateway/src/index.ts", "target": "gateway" } ], "ignored_routes": 24, "configured_exclusions": 18, "configuration_findings": [], "notes": [] }, "runtime_contract_audit": { "status": "verified", "actions": 77, "contracts": 77, "contract_module": "apps/gateway/action-contracts.mjs", "validator_sources": [ "apps/gateway/src/index.ts" ], "authorization_sources": [ "apps/gateway/src/index.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "topolo-platform/services/TopoloNexus/topolo.mobile-experience.json", "contract": { "version": "2026-06-29", "status": "approved", "mode": "native_capability", "appId": "app_topolo_nexus", "localizationNamespace": "nexus", "permissions": [ "apps:read", "audit:read", "usage:read" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/apps", "auth": { "audience": "topolo-nexus", "scopes": [ "apps:read", "audit:read", "usage:read" ] }, "routes": [ { "path": "/apps", "apiPath": "/api/apps", "title": "Apps", "titleKey": "nexus.mobile.routes.apps.title", "template": "record.list", "dataSource": "nexus.apps.list" }, { "path": "/audit", "apiPath": "/api/audit", "title": "Audit", "titleKey": "nexus.mobile.routes.audit.title", "template": "record.list", "dataSource": "nexus.audit.list" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "GET", "path": "/health", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/index.ts" }, { "method": "POST", "path": "/internal/platform/encryption/master-key/rewrap", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/index.ts" }, { "method": "GET", "path": "/api/app-identity", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/index.ts" }, { "method": "GET", "path": "/api/widget", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/index.ts" }, { "method": "GET", "path": "/api/organization", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/index.ts" }, { "method": "POST", "path": "/api/organizations/provision", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/index.ts" }, { "method": "GET", "path": "/api/audit", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/index.ts" }, { "method": "POST", "path": "/completions", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/ai.ts" }, { "method": "POST", "path": "/translations", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/ai.ts" }, { "method": "POST", "path": "/embeddings", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/ai.ts" }, { "method": "POST", "path": "/markdown", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/ai.ts" }, { "method": "POST", "path": "/image/describe", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/ai.ts" }, { "method": "POST", "path": "/autorag/search", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/ai.ts" }, { "method": "POST", "path": "/transcriptions", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/ai.ts" }, { "method": "POST", "path": "/generations", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/ai.ts" }, { "method": "GET", "path": "/models", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/ai.ts" }, { "method": "GET", "path": "/health/:provider", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/ai.ts" }, { "method": "GET", "path": "/", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/apps.ts" }, { "method": "GET", "path": "/:appSlug", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/apps.ts" }, { "method": "PATCH", "path": "/:appSlug", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/apps.ts" }, { "method": "GET", "path": "/meta/capabilities", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/apps.ts" }, { "method": "GET", "path": "/meta/models", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/apps.ts" }, { "method": "GET", "path": "/connections", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/email.ts" }, { "method": "POST", "path": "/connections", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/email.ts" }, { "method": "PATCH", "path": "/connections/:id", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/email.ts" }, { "method": "GET", "path": "/profiles", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/email.ts" }, { "method": "POST", "path": "/profiles", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/email.ts" }, { "method": "PATCH", "path": "/profiles/:id", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/email.ts" }, { "method": "POST", "path": "/send", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/email.ts" }, { "method": "GET", "path": "/governance", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/models.ts" }, { "method": "POST", "path": "/sync", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/models.ts" }, { "method": "POST", "path": "/stripe", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/payments.ts" }, { "method": "POST", "path": "/connections/list", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-integrations.ts" }, { "method": "POST", "path": "/connections/provider-lookup", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-integrations.ts" }, { "method": "POST", "path": "/connections/upsert", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-integrations.ts" }, { "method": "POST", "path": "/connections/changes", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-integrations.ts" }, { "method": "POST", "path": "/connections/disconnect", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-integrations.ts" }, { "method": "GET", "path": "/app-credentials/health", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-integrations.ts" }, { "method": "POST", "path": "/app-credentials/list", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-integrations.ts" }, { "method": "POST", "path": "/app-credentials/upsert", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-integrations.ts" }, { "method": "POST", "path": "/app-credentials/resolve", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-integrations.ts" }, { "method": "POST", "path": "/connections/resolve", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-integrations.ts" }, { "method": "POST", "path": "/check", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-ratelimit.ts" }, { "method": "POST", "path": "/verify", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-turnstile.ts" }, { "method": "POST", "path": "/events", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-usage.ts" }, { "method": "GET", "path": "/turnstile", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-usage.ts" }, { "method": "POST", "path": "/meter-settings/backfill", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-usage.ts" }, { "method": "POST", "path": "/channels/profile", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-youtube.ts" }, { "method": "POST", "path": "/videos/upload", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/platform-youtube.ts" }, { "method": "GET", "path": "/", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/preferences.ts" }, { "method": "GET", "path": "/:useCase", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/preferences.ts" }, { "method": "PUT", "path": "/:useCase", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/preferences.ts" }, { "method": "DELETE", "path": "/:useCase", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/preferences.ts" }, { "method": "GET", "path": "/available/models", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/preferences.ts" }, { "method": "GET", "path": "/", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/privacy.ts" }, { "method": "DELETE", "path": "/", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/privacy.ts" }, { "method": "GET", "path": "/", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/provider-credentials.ts" }, { "method": "PUT", "path": "/:provider", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/provider-credentials.ts" }, { "method": "PATCH", "path": "/:provider", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/provider-credentials.ts" }, { "method": "GET", "path": "/overview", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "GET", "path": "/daily", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "GET", "path": "/by-app", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "GET", "path": "/by-user", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "GET", "path": "/by-model", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "GET", "path": "/recent", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "GET", "path": "/budget", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "PUT", "path": "/budget", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "GET", "path": "/limits", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "GET", "path": "/limits/options", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "PUT", "path": "/limits", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "GET", "path": "/projection", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "GET", "path": "/spend", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "GET", "path": "/events", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "GET", "path": "/key-health", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "GET", "path": "/snapshots/daily", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/usage.ts" }, { "method": "GET", "path": "/whatsapp", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/webhooks-meta.ts" }, { "method": "POST", "path": "/whatsapp", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/webhooks-meta.ts" }, { "method": "POST", "path": "/stripe", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/webhooks.ts" }, { "method": "POST", "path": "/exchange", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/whatsapp-embedded-signup.ts" }, { "method": "POST", "path": "/", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/whatsapp-templates.ts" }, { "method": "GET", "path": "/", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/whatsapp-templates.ts" }, { "method": "POST", "path": "/send", "source_path": "topolo-platform/services/TopoloNexus/apps/gateway/src/routes/whatsapp.ts" } ], "ui_routes": [ { "path": "/", "source_path": "topolo-platform/services/TopoloNexus/apps/dashboard/src/App.tsx" }, { "path": "/login", "source_path": "topolo-platform/services/TopoloNexus/apps/dashboard/src/App.tsx" }, { "path": "/auth/callback", "source_path": "topolo-platform/services/TopoloNexus/apps/dashboard/src/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/nexus", "internal/apps/nexus" ], "present_paths": [ "applications/nexus", "internal/apps/nexus" ], "missing_paths": [], "human_reference": "/systems/topolo-nexus", "machine_reference": "/machine/systems/topolo-nexus.json", "action_examples": 77, "action_schemas": 77 }, "source_findings": [ { "type": "uncatalogued_routes", "source_path": "topolo-platform/services/TopoloNexus/topolo.app.json", "detail": [ { "key": "POST /internal/platform/encryption/master-key/rewrap", "method": "POST", "path": "/internal/platform/encryption/master-key/rewrap", "source": "apps/gateway/src/index.ts", "target": "gateway" } ] } ] }, "topolo-one": { "id": "topolo-one", "name": "TopoloOne", "slug": "topolo-one", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloOne" ], "source_revisions": [ { "source_path": "apps/TopoloOne", "repository": "apps/TopoloOne", "revision": "a6c9fe5faa3e4cea7302101db6f6c1df60495711", "ref": "origin/staging" } ], "source_counts": { "source_files": 340, "test_files": 186, "test_cases": 0, "migration_files": 5, "database_tables": 0, "manifests": 1, "deploy_targets": 3, "actions": 24, "mobile_contracts": 1, "notifications": 0, "package_manifests": 5, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloOne/topolo.app.json", "service_slug": "topolo-one", "name": "TopoloOne", "app_id": "app_topolo_one", "compatibility_date": "2026-04-10", "primary_target": "web", "environments": [ "development", "production", "staging" ], "targets": [ { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-one", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "AUTH_API_URL" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null } ] }, { "name": "marketing", "kind": "worker", "directory": "apps/marketing", "main": "worker/index.js", "worker_name": "topolo-one-website", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "BLOG_API_BASE_URL", "ENVIRONMENT", "INSIGHTS_API_BASE_URL", "INSIGHTS_WORKSPACE_ID", "NEXT_PUBLIC_AUTH_URL", "NEXT_PUBLIC_DEVELOPER_PORTAL_URL", "NEXT_PUBLIC_DOCS_URL", "NEXT_PUBLIC_ONE_URL", "NEXT_PUBLIC_SIGNUP_MODE", "NEXT_PUBLIC_SITE_URL", "NEXT_PUBLIC_TOPOLO_CONSENT_BASE_URL", "NEXT_PUBLIC_TOPOLO_CONSENT_SDK_KEY", "NEXT_PUBLIC_TURNSTILE_SITE_KEY", "NEXUS_GATEWAY_URL", "NEXUS_ORGANIZATION_ID", "TOPOLO_AGENT_PUBLIC_CHAT_URL", "TOPOLO_ONE_BILLING_URL", "TOPOLO_PAY_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "BILLING_DB", "target": null }, { "kind": "kv", "binding": "WAITLIST_KV", "target": null }, { "kind": "kv", "binding": "BOOKING_KV", "target": null }, { "kind": "kv", "binding": "SUBS_KV", "target": null } ] }, { "name": "api", "kind": "worker", "directory": "apps/api", "main": "dist/index.js", "worker_name": "topolo-one-api", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "ALLOWED_ORIGINS", "AUTH_API_URL", "ENVIRONMENT", "LOG_LEVEL", "NODE_ENV", "SERVICE_NAME", "STORE_API_BASE_URL", "TOPOLO_PAY_URL", "TOPOLO_SEED_APP_ID" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "CATALOG_DB", "target": null }, { "kind": "d1", "binding": "LAUNCH_DB", "target": null }, { "kind": "d1", "binding": "PUSH_DB", "target": null }, { "kind": "d1", "binding": "BILLING_DB", "target": null }, { "kind": "kv", "binding": "ONECLICK_KV", "target": null }, { "kind": "services", "binding": "DASHBOARD_APP", "target": null }, { "kind": "services", "binding": "DASHBOARD_APP", "target": null }, { "kind": "services", "binding": "DASHBOARD_APP", "target": null } ] } ], "notifications": [], "notification_contract": { "source_path": null, "role": "consumer_only", "schema_version": null, "owner_app_id": null, "events": [] }, "actions": [ { "name": "workspaces.delete", "title": "Archive workspace", "description": "Archive an empty workspace: TopoloOne confirms it holds no data, then the platform archives the record.", "method": "DELETE", "path": "/api/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 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.export", "title": "Export organization data", "description": "Export TopoloOne-owned launch, push, billing, cache, and workspace-mirror data for the authenticated organization with credential fields redacted.", "method": "GET", "path": "/api/organizations/{organizationId}/data", "permission": "settings:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "organizationId": "example" }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/example/data", "body": null }, "effects": "Reads state through GET /api/organizations/{organizationId}/data without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.erase", "title": "Erase organization data", "description": "Erase TopoloOne-owned organization data after refusing active billing subscriptions, with explicit pending verification for eventually consistent KV.", "method": "DELETE", "path": "/api/organizations/{organizationId}/data", "permission": "settings:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "organizationId": "example" }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/example/data", "body": null }, "effects": "May change state through DELETE /api/organizations/{organizationId}/data. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "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", "authorizationMode": "runtime", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "apps.list", "title": "List launcher apps", "description": "List apps visible in TopoloOne.", "method": "GET", "path": "/api/apps", "permission": "apps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List launcher apps.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/apps", "body": null }, "effects": "Reads state through GET /api/apps without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/apps", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "dashboard.get", "title": "Get composed dashboard", "description": "Get the current organization launcher catalog, preferences, users, and canonical store icons.", "method": "GET", "path": "/api/dashboard", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "services": { "type": "array", "items": {} }, "availableServices": { "type": "array", "items": {} } }, "required": [ "services", "availableServices" ], "additionalProperties": {} } }, "required": [ "data" ], "additionalProperties": false }, "authorizationMode": "runtime", "documentation": { "example_input": { "org_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/dashboard", "body": null }, "effects": "Reads state through GET /api/dashboard without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/dashboard", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "checkout.quote", "title": "Quote checkout", "description": "Quote a cart checkout.", "method": "POST", "path": "/api/cart/quote", "permission": "entitlements:read", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1 }, "seats": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "slug" ], "additionalProperties": false } }, "appSlugs": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "seats": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "billing": { "type": "string", "enum": [ "monthly", "annual" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Quote checkout.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "items": [ { "slug": "example" } ], "appSlugs": [ "example" ], "seats": 1 }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/cart/quote", "body": { "items": [ { "slug": "example" } ], "appSlugs": [ "example" ], "seats": 1 } }, "effects": "May change state through POST /api/cart/quote. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/cart/quote", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "checkout.create", "title": "Create checkout", "description": "Create a checkout session.", "method": "POST", "path": "/api/cart/checkout", "permission": "workflows:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1 }, "seats": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "slug" ], "additionalProperties": false } }, "appSlugs": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "seats": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "billing": { "type": "string", "enum": [ "monthly", "annual" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create checkout.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "items": [ { "slug": "example" } ], "appSlugs": [ "example" ], "seats": 1 }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/cart/checkout", "body": { "items": [ { "slug": "example" } ], "appSlugs": [ "example" ], "seats": 1 } }, "effects": "May change state through POST /api/cart/checkout. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/cart/checkout", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widgets.aggregate", "title": "Widgets Aggregate", "description": "Call POST /api/widgets.", "method": "POST", "path": "/api/widgets", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contextKey": { "type": "string", "minLength": 1 }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "base_url": { "type": "string", "minLength": 1 }, "settings": {}, "category": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "supportedContexts": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "isInstalled": { "type": "boolean" }, "widgetEndpoint": { "type": "string", "minLength": 1 }, "widget_endpoint": { "type": "string", "minLength": 1 }, "widgetOrigin": { "type": "string", "minLength": 1 }, "widget_origin": { "type": "string", "minLength": 1 }, "widgetsEnabled": { "type": "boolean" }, "widget_enabled": { "type": "boolean" }, "refreshInterval": { "type": "number" } }, "required": [ "id" ], "additionalProperties": {} } } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Widgets Aggregate.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "contextKey": "example", "services": [ { "id": "00000000-0000-4000-8000-000000000000" } ] }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/widgets", "body": { "contextKey": "example", "services": [ { "id": "00000000-0000-4000-8000-000000000000" } ] } }, "effects": "May change state through POST /api/widgets. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/widgets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget_snapshots.create", "title": "Widget Snapshots Create", "description": "Call POST /api/widget-snapshots.", "method": "POST", "path": "/api/widget-snapshots", "permission": "widgets:read", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "preset": { "type": "string", "minLength": 1 }, "contextKey": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "service": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "base_url": { "type": "string", "minLength": 1 }, "settings": {}, "category": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "supportedContexts": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "isInstalled": { "type": "boolean" }, "widgetEndpoint": { "type": "string", "minLength": 1 }, "widget_endpoint": { "type": "string", "minLength": 1 }, "widgetOrigin": { "type": "string", "minLength": 1 }, "widget_origin": { "type": "string", "minLength": 1 }, "widgetsEnabled": { "type": "boolean" }, "widget_enabled": { "type": "boolean" }, "refreshInterval": { "type": "number" } }, "required": [ "id" ], "additionalProperties": {} }, { "type": "null" } ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "base_url": { "type": "string", "minLength": 1 }, "settings": {}, "category": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "supportedContexts": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "isInstalled": { "type": "boolean" }, "widgetEndpoint": { "type": "string", "minLength": 1 }, "widget_endpoint": { "type": "string", "minLength": 1 }, "widgetOrigin": { "type": "string", "minLength": 1 }, "widget_origin": { "type": "string", "minLength": 1 }, "widgetsEnabled": { "type": "boolean" }, "widget_enabled": { "type": "boolean" }, "refreshInterval": { "type": "number" } }, "required": [ "id" ], "additionalProperties": {} } }, "metricKeys": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Widget Snapshots Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "preset": "example", "contextKey": "example", "appId": "example" }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/widget-snapshots", "body": { "preset": "example", "contextKey": "example", "appId": "example" } }, "effects": "May change state through POST /api/widget-snapshots. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/widget-snapshots", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.create", "title": "Apps Create", "description": "Call POST /api/apps.", "method": "POST", "path": "/api/apps", "permission": "apps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "icon": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "developer": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 }, "base_url": { "type": "string", "minLength": 1 }, "launch_url_template": { "type": "string", "minLength": 1 }, "required_permissions": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "optional_permissions": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "status": { "type": "string", "enum": [ "active", "inactive", "maintenance" ] }, "is_system_app": { "type": "boolean" } }, "required": [ "id", "name", "base_url" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Apps Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "base_url": "https://example.com" }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/apps", "body": { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "base_url": "https://example.com" } }, "effects": "May change state through POST /api/apps. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/apps", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.update", "title": "Apps Update", "description": "Call PATCH /api/apps/{id}.", "method": "PATCH", "path": "/api/apps/{id}", "permission": "apps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "icon": { "type": "string", "minLength": 1 }, "required_permissions": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "optional_permissions": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "base_url": { "type": "string", "minLength": 1 }, "launch_url_template": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "active", "inactive", "maintenance" ] }, "is_system_app": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Apps Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/apps/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PATCH /api/apps/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/apps/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "apps.delete", "title": "Apps Delete", "description": "Call DELETE /api/apps/{id}.", "method": "DELETE", "path": "/api/apps/{id}", "permission": "apps:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Apps Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/apps/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/apps/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/apps/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "billing.organization_preview", "title": "Billing Organization Preview", "description": "Call POST /api/billing/organizations/{orgId}/preview.", "method": "POST", "path": "/api/billing/organizations/{orgId}/preview", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "targetSeatQuantity": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seatSummary": {} }, "required": [ "orgId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Billing Organization Preview.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "service", "allowedServices": [ "topolo-auth" ], "documentation": { "example_input": { "orgId": "example" }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/billing/organizations/example/preview", "body": { "orgId": "example" } }, "effects": "May change state through POST /api/billing/organizations/{orgId}/preview. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/billing/organizations/*/preview", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "push_subscriptions.create", "title": "Push Subscriptions Create", "description": "Call POST /api/push/subscriptions.", "method": "POST", "path": "/api/push/subscriptions", "permission": "notifications:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "endpoint": { "type": "string", "minLength": 1 }, "keys": { "type": "object", "properties": { "p256dh": { "type": "string", "minLength": 1 }, "auth": { "type": "string", "minLength": 1 } }, "required": [ "p256dh", "auth" ], "additionalProperties": false } }, "required": [ "endpoint", "keys" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Push Subscriptions Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "endpoint": "example", "keys": { "p256dh": "example", "auth": "example" } }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/push/subscriptions", "body": { "endpoint": "example", "keys": { "p256dh": "example", "auth": "example" } } }, "effects": "May change state through POST /api/push/subscriptions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/push/subscriptions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "push_subscriptions.delete", "title": "Push Subscriptions Delete", "description": "Call DELETE /api/push/subscriptions.", "method": "DELETE", "path": "/api/push/subscriptions", "permission": "notifications:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "endpoint": { "type": "string", "minLength": 1 } }, "required": [ "endpoint" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Push Subscriptions Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "endpoint": "example" }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/push/subscriptions", "body": null }, "effects": "May change state through DELETE /api/push/subscriptions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/push/subscriptions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "push.vapid_key.get", "title": "Push Vapid Key Get", "description": "Call GET /api/push/vapid-key.", "method": "GET", "path": "/api/push/vapid-key", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Push Vapid Key Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "public", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/push/vapid-key", "body": null }, "effects": "Reads state through GET /api/push/vapid-key without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/push/vapid-key", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "launch.get", "title": "Launch Get", "description": "Call GET /api/launch/{appId}.", "method": "GET", "path": "/api/launch/{appId}", "permission": "launcher:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Launch Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/launch/example", "body": null }, "effects": "Reads state through GET /api/launch/{appId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/launch/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "launch.create", "title": "Launch Create", "description": "Call POST /api/launch/{appId}.", "method": "POST", "path": "/api/launch/{appId}", "permission": "launches:read", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Launch Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/launch/example", "body": { "appId": "example" } }, "effects": "May change state through POST /api/launch/{appId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/launch/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "launch.secure_token.create", "title": "Launch Secure Token Create", "description": "Call POST /api/launch/secure-token.", "method": "POST", "path": "/api/launch/secure-token", "permission": "launches:read", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "callbackUrl": { "type": "string", "minLength": 1 } }, "required": [ "appId", "callbackUrl" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Launch Secure Token Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "appId": "example", "callbackUrl": "https://example.com" }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/launch/secure-token", "body": { "appId": "example", "callbackUrl": "https://example.com" } }, "effects": "May change state through POST /api/launch/secure-token. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/launch/secure-token", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "track.create", "title": "Track Create", "description": "Call POST /api/track.", "method": "POST", "path": "/api/track", "permission": "dashboard:read", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "appId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Track Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/track", "body": { "appId": "example" } }, "effects": "May change state through POST /api/track. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/track", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.status.get", "title": "Admin Status Get", "description": "Call GET /api/admin/status.", "method": "GET", "path": "/api/admin/status", "permission": "settings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Admin Status Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/status", "body": null }, "effects": "Reads state through GET /api/admin/status without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/status", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.apps.list", "title": "Admin Apps List", "description": "Call GET /api/admin/apps.", "method": "GET", "path": "/api/admin/apps", "permission": "apps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Admin Apps List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/apps", "body": null }, "effects": "Reads state through GET /api/admin/apps without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/apps", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.categories.list", "title": "Admin Categories List", "description": "Call GET /api/admin/categories.", "method": "GET", "path": "/api/admin/categories", "permission": "apps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Admin Categories List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-one --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/categories", "body": null }, "effects": "Reads state through GET /api/admin/categories without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/categories", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 31, "matched_actions": 24, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 7, "configured_exclusions": 5, "configuration_findings": [], "notes": [ "analyzed source for api (manifest points at dist build)" ] }, "runtime_contract_audit": { "status": "verified", "actions": 24, "contracts": 24, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/index.ts" ], "authorization_sources": [ "apps/api/src/index.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloOne/topolo.mobile-experience.json", "contract": { "version": "2026-07-03", "status": "approved", "mode": "native_capability", "appId": "app_topolo_one", "localizationNamespace": "one", "permissions": [ "apps:read", "dashboard:read" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/apps", "auth": { "audience": "topolo-one", "scopes": [ "apps:read", "dashboard:read" ], "orgContext": "required" }, "routes": [ { "path": "/apps", "apiPath": "/api/apps", "title": "Apps", "titleKey": "one.mobile.routes.apps.title", "template": "record.list", "dataSource": "one.apps.list", "detailRoute": "/apps/:slug" }, { "path": "/apps/:slug", "apiPath": "/api/apps/:slug", "title": "App", "titleKey": "one.mobile.routes.appDetail.title", "template": "record.detail", "dataSource": "one.apps.detail" }, { "path": "/dashboard", "apiPath": "/api/widget", "title": "Dashboard", "titleKey": "one.mobile.routes.dashboard.title", "template": "record.detail", "dataSource": "one.dashboard.detail" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "LITERAL", "path": "/health", "source_path": "apps/TopoloOne/apps/api/src/middleware/rate-limit.ts" }, { "method": "GET", "path": "/health", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "GET", "path": "/", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "GET", "path": "/api", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "GET", "path": "/api/dashboard", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "GET", "path": "/api/apps", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "DELETE", "path": "/api/workspaces/:workspaceId", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "GET", "path": "/api/organizations/:organizationId/data", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "DELETE", "path": "/api/organizations/:organizationId/data", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "GET", "path": "/api/widget", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "POST", "path": "/api/widgets", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "POST", "path": "/api/widget-snapshots", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "POST", "path": "/api/apps", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "DELETE", "path": "/api/apps/:id", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "POST", "path": "/api/cart/quote", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "POST", "path": "/api/cart/checkout", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "POST", "path": "/api/billing/organizations/:orgId/preview", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "POST", "path": "/api/logout", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "POST", "path": "/api/push/subscriptions", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "DELETE", "path": "/api/push/subscriptions", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "GET", "path": "/api/push/vapid-key", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "GET", "path": "/api/launch/:appId", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "POST", "path": "/api/launch/secure-token", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "POST", "path": "/api/launch/:appId", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "POST", "path": "/api/track", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "GET", "path": "/api/admin/status", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "PATCH", "path": "/api/apps/:id", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "GET", "path": "/api/admin/apps", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "GET", "path": "/api/admin/categories", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "GET", "path": "/test/bindings", "source_path": "apps/TopoloOne/apps/api/src/router.ts" }, { "method": "ALL", "path": "*", "source_path": "apps/TopoloOne/apps/api/src/router.ts" } ], "ui_routes": [ { "path": "/dashboard", "source_path": "apps/TopoloOne/apps/web/src/App.tsx" }, { "path": "/apps", "source_path": "apps/TopoloOne/apps/web/src/App.tsx" }, { "path": "/apps/:slug", "source_path": "apps/TopoloOne/apps/web/src/App.tsx" }, { "path": "/cart", "source_path": "apps/TopoloOne/apps/web/src/App.tsx" }, { "path": "/actions", "source_path": "apps/TopoloOne/apps/web/src/App.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloOne/apps/web/src/App.tsx" }, { "path": "/settings/*", "source_path": "apps/TopoloOne/apps/web/src/App.tsx" }, { "path": "/onboarding", "source_path": "apps/TopoloOne/apps/web/src/App.tsx" }, { "path": "/error/:code?", "source_path": "apps/TopoloOne/apps/web/src/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/one", "internal/apps/topolo-one", "internal/platform/application-entry-and-admission" ], "present_paths": [ "applications/one", "internal/apps/topolo-one", "internal/platform/application-entry-and-admission" ], "missing_paths": [], "human_reference": "/systems/topolo-one", "machine_reference": "/machine/systems/topolo-one.json", "action_examples": 24, "action_schemas": 24 }, "source_findings": [] }, "topolo-p2p": { "id": "topolo-p2p", "name": "TopoloP2P", "slug": "topolo-p2p", "kind": "application", "visibility": "public", "repo_paths": [ "system-apps/TopoloP2P" ], "source_revisions": [ { "source_path": "system-apps/TopoloP2P", "repository": "system-apps/TopoloP2P", "revision": "0ee9f3cb3b2f95f59806528354a9c86bf9226e23", "ref": "origin/staging" } ], "source_counts": { "source_files": 50, "test_files": 29, "test_cases": 0, "migration_files": 10, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 20, "mobile_contracts": 1, "notifications": 9, "package_manifests": 1, "deployment_configs": 0 }, "manifests": [ { "source_path": "system-apps/TopoloP2P/topolo.app.json", "service_slug": "topolo-p2p", "name": "topolo-p2p", "app_id": "app_topolo_p2p", "compatibility_date": "2026-04-23", "primary_target": "web", "environments": [ "development", "production", "staging" ], "targets": [ { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/worker.ts", "worker_name": "topolo-p2p-api", "subdomain": null, "healthcheck_path": "/api/health", "variable_names": [ "AUTH_BASE_URL", "ENVIRONMENT", "P2P_PUBLIC_BASE_URL", "TOPOLO_NOTIFY_URL", "TOPOLO_PAY_URL", "TOPOLO_SEED_APP_ID" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "P2P_CORE_DB", "target": null }, { "kind": "d1", "binding": "P2P_RUNTIME_DB", "target": null }, { "kind": "d1", "binding": "P2P_LEDGER_DB", "target": null }, { "kind": "d1", "binding": "P2P_AUDIT_DB", "target": null } ] }, { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-p2p", "subdomain": "p2p", "healthcheck_path": "/api/health", "variable_names": [ "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null } ] } ], "notifications": [ "p2p.connection.accepted", "p2p.connection.requested", "p2p.connection.revoked", "p2p.hold.placed", "p2p.hold.released", "p2p.policy.violation", "p2p.settlement.completed", "p2p.settlement.created", "p2p.settlement.failed" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_p2p", "events": [ { "type": "p2p.connection.accepted", "version": 1, "description": "A P2P connection was durably transitioned to active.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "connection_id", "counterparty_organization_id", "status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "connection_id": { "type": "string", "minLength": 1 }, "counterparty_organization_id": { "type": "string", "minLength": 1 }, "status": { "const": "active" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "P2P connection accepted", "body": "Connection with org_partner is active.", "object_id": "conn_1", "connection_id": "conn_1", "counterparty_organization_id": "org_partner", "status": "active", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://p2p.topolo.app/connections" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^p2p:connection-active:" } }, { "type": "p2p.connection.requested", "version": 1, "description": "A P2P connection request was durably persisted as pending.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "connection_id", "counterparty_organization_id", "status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "connection_id": { "type": "string", "minLength": 1 }, "counterparty_organization_id": { "type": "string", "minLength": 1 }, "status": { "const": "pending" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "P2P connection requested", "body": "Connection with org_partner is pending.", "object_id": "conn_1", "connection_id": "conn_1", "counterparty_organization_id": "org_partner", "status": "pending", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://p2p.topolo.app/connections" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^p2p:connection-pending:" } }, { "type": "p2p.connection.revoked", "version": 1, "description": "An active or pending P2P connection was durably revoked.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "connection_id", "counterparty_organization_id", "previous_status", "status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "connection_id": { "type": "string", "minLength": 1 }, "counterparty_organization_id": { "type": "string", "minLength": 1 }, "previous_status": { "type": "string", "minLength": 1 }, "status": { "const": "revoked" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "P2P connection revoked", "body": "Connection with org_partner was revoked.", "object_id": "conn_1", "connection_id": "conn_1", "counterparty_organization_id": "org_partner", "previous_status": "active", "status": "revoked", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://p2p.topolo.app/connections" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^p2p:connection-revoked:" } }, { "type": "p2p.hold.placed", "version": 1, "description": "A dispute durably created a new active P2P hold.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "hold_id", "request_id", "counterparty_organization_id", "reason", "status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "hold_id": { "type": "string", "minLength": 1 }, "request_id": { "type": "string", "minLength": 1 }, "counterparty_organization_id": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 }, "status": { "const": "active" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "P2P hold placed", "body": "A hold was placed on action req_1: delivery disputed.", "object_id": "hold_1", "hold_id": "hold_1", "request_id": "req_1", "counterparty_organization_id": "org_partner", "reason": "delivery disputed", "status": "active", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://p2p.topolo.app/actions/req_1" } ], "dataClassification": "confidential", "sensitiveFields": [ "reason" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^p2p:hold-placed:" } }, { "type": "p2p.hold.released", "version": 1, "description": "An active or disputed P2P hold was durably released.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "hold_id", "request_id", "counterparty_organization_id", "resolution", "status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "hold_id": { "type": "string", "minLength": 1 }, "request_id": { "type": "string", "minLength": 1 }, "counterparty_organization_id": { "type": "string", "minLength": 1 }, "resolution": { "enum": [ "buyer", "seller" ] }, "status": { "const": "released" }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "P2P hold released", "body": "The hold on action req_1 was released to the seller.", "object_id": "hold_1", "hold_id": "hold_1", "request_id": "req_1", "counterparty_organization_id": "org_partner", "resolution": "seller", "status": "released", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://p2p.topolo.app/actions/req_1" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^p2p:hold-released:" } }, { "type": "p2p.policy.violation", "version": 1, "description": "A persisted P2P policy decision rejected an action request.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "decision_id", "request_id", "capability_id", "counterparty_organization_id", "rationale", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "decision_id": { "type": "string", "minLength": 1 }, "request_id": { "type": "string", "minLength": 1 }, "capability_id": { "type": "string", "minLength": 1 }, "counterparty_organization_id": { "type": "string", "minLength": 1 }, "rationale": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "P2P policy blocked an action", "body": "The Print labels request was blocked: capability_blocked.", "object_id": "policy_1", "decision_id": "policy_1", "request_id": "req_1", "capability_id": "cap_print", "counterparty_organization_id": "org_partner", "rationale": "capability_blocked", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://p2p.topolo.app/actions/req_1" } ], "dataClassification": "confidential", "sensitiveFields": [ "rationale" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^p2p:policy-violation:" } }, { "type": "p2p.settlement.completed", "version": 1, "description": "TopoloPay confirmed that a persisted P2P settlement completed.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "batch_id", "counterparty_organization_id", "total_minor", "currency", "status", "pay_settlement_id", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "batch_id": { "type": "string", "minLength": 1 }, "counterparty_organization_id": { "type": "string", "minLength": 1 }, "total_minor": { "type": "integer", "minimum": 1 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "status": { "const": "paid" }, "pay_settlement_id": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "P2P settlement completed", "body": "2500 USD settled successfully.", "object_id": "batch_1", "batch_id": "batch_1", "counterparty_organization_id": "org_partner", "total_minor": 2500, "currency": "USD", "status": "paid", "pay_settlement_id": "payset_1", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://p2p.topolo.app/settlements" } ], "dataClassification": "confidential", "sensitiveFields": [ "total_minor" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^p2p:settlement-completed:" } }, { "type": "p2p.settlement.created", "version": 1, "description": "A P2P settlement batch and its Pay submission were durably persisted.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "batch_id", "counterparty_organization_id", "total_minor", "currency", "status", "pay_settlement_id", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "batch_id": { "type": "string", "minLength": 1 }, "counterparty_organization_id": { "type": "string", "minLength": 1 }, "total_minor": { "type": "integer", "minimum": 1 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "status": { "enum": [ "pending", "submitted" ] }, "pay_settlement_id": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "P2P settlement created", "body": "2500 USD was submitted for settlement.", "object_id": "batch_1", "batch_id": "batch_1", "counterparty_organization_id": "org_partner", "total_minor": 2500, "currency": "USD", "status": "submitted", "pay_settlement_id": "payset_1", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://p2p.topolo.app/settlements" } ], "dataClassification": "confidential", "sensitiveFields": [ "total_minor" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^p2p:settlement-created:" } }, { "type": "p2p.settlement.failed", "version": 1, "description": "A persisted P2P settlement failed during submission or Pay processing.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "batch_id", "counterparty_organization_id", "total_minor", "currency", "status", "pay_settlement_id", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "batch_id": { "type": "string", "minLength": 1 }, "counterparty_organization_id": { "type": "string", "minLength": 1 }, "total_minor": { "type": "integer", "minimum": 1 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "status": { "const": "failed" }, "pay_settlement_id": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "P2P settlement failed", "body": "2500 USD failed to settle.", "object_id": "batch_1", "batch_id": "batch_1", "counterparty_organization_id": "org_partner", "total_minor": 2500, "currency": "USD", "status": "failed", "pay_settlement_id": "payset_1", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://p2p.topolo.app/settlements" } ], "dataClassification": "confidential", "sensitiveFields": [ "total_minor" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^p2p:settlement-failed:" } } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "directory: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-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "directory.capabilities.list", "title": "List P2P capabilities", "description": "List P2P directory capabilities.", "method": "GET", "path": "/api/directory/capabilities", "authorizationMode": "public", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List P2P capabilities.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "limit": 1 }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/directory/capabilities", "body": null }, "effects": "Reads state through GET /api/directory/capabilities without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/directory/capabilities", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "directory.capabilities.get", "title": "Get P2P capability", "description": "Get one public P2P directory capability.", "method": "GET", "path": "/api/directory/capabilities/{capabilityId}", "authorizationMode": "public", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "capabilityId": { "type": "string", "minLength": 1 } }, "required": [ "capabilityId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "capabilityId": "example" }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/directory/capabilities/example", "body": null }, "effects": "Reads state through GET /api/directory/capabilities/{capabilityId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/directory/capabilities/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "connections.list", "title": "List P2P connections", "description": "List P2P connections.", "method": "GET", "path": "/api/connections", "permission": "directory:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List P2P connections.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/connections", "body": null }, "effects": "Reads state through GET /api/connections without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/connections", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "connections.create", "title": "Create P2P connection", "description": "Create a P2P connection.", "method": "POST", "path": "/api/connections", "permission": "connections:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "counterparty_org_id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "pending", "active", "suspended" ] } }, "required": [ "counterparty_org_id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create P2P connection.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "counterparty_org_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/connections", "body": { "counterparty_org_id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/connections. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/connections", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "connections.revoke", "title": "Revoke P2P connection", "description": "Revoke a P2P connection.", "method": "DELETE", "path": "/api/connections/{connectionId}", "permission": "connections:write", "authorizationMode": "static", "readOnly": false, "destructive": true, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "connectionId": { "type": "string", "minLength": 1 } }, "required": [ "connectionId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Revoke P2P connection.", "additionalProperties": true }, "agentAccess": "confirm", "documentation": { "example_input": { "connectionId": "example" }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/connections/example", "body": null }, "effects": "May change state through DELETE /api/connections/{connectionId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/connections/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ledger.list", "title": "List P2P ledger", "description": "List P2P ledger entries.", "method": "GET", "path": "/api/ledger", "permission": "ledger:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List P2P ledger.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/ledger", "body": null }, "effects": "Reads state through GET /api/ledger without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/ledger", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "settlements.preview", "title": "Preview settlements", "description": "Preview P2P settlement batches.", "method": "POST", "path": "/api/settlements/preview", "permission": "settlements:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "buyer_org_id": { "type": "string", "minLength": 1 }, "seller_org_id": { "type": "string", "minLength": 1 }, "currency": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Preview settlements.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "buyer_org_id": "00000000-0000-4000-8000-000000000000", "seller_org_id": "00000000-0000-4000-8000-000000000000", "currency": "USD" }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/settlements/preview", "body": { "buyer_org_id": "00000000-0000-4000-8000-000000000000", "seller_org_id": "00000000-0000-4000-8000-000000000000", "currency": "USD" } }, "effects": "May change state through POST /api/settlements/preview. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/settlements/preview", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "settlements.create", "title": "Create settlement", "description": "Create a P2P settlement.", "method": "POST", "path": "/api/settlements/create", "permission": "settlements:approve", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "buyer_org_id": { "type": "string", "minLength": 1 }, "seller_org_id": { "type": "string", "minLength": 1 }, "currency": { "type": "string", "minLength": 1 }, "trigger": { "type": "string", "enum": [ "threshold", "schedule", "manual", "invoice", "delivery" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create settlement.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "buyer_org_id": "00000000-0000-4000-8000-000000000000", "seller_org_id": "00000000-0000-4000-8000-000000000000", "currency": "USD" }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/settlements/create", "body": { "buyer_org_id": "00000000-0000-4000-8000-000000000000", "seller_org_id": "00000000-0000-4000-8000-000000000000", "currency": "USD" } }, "effects": "May change state through POST /api/settlements/create. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/settlements/create", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "policies.get", "title": "Get P2P policy", "description": "Get P2P policy.", "method": "GET", "path": "/api/policies", "permission": "policy:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get P2P policy.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/policies", "body": null }, "effects": "Reads state through GET /api/policies without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/policies", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "policies.update", "title": "Update P2P policy", "description": "Update P2P policy.", "method": "PUT", "path": "/api/policies", "permission": "policy:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "auto_approve_under_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "agent_spend_limit_minor_per_day": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "human_approval_threshold_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unknown_counterparty_requires_approval": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string" } ] }, "blocked_capability_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "minLength": 1 } }, { "type": "string", "minLength": 1 } ] }, "trusted_counterparty_org_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "minLength": 1 } }, { "type": "string", "minLength": 1 } ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update P2P policy.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "auto_approve_under_minor": 1, "agent_spend_limit_minor_per_day": 1, "human_approval_threshold_minor": 1 }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/policies", "body": { "auto_approve_under_minor": 1, "agent_spend_limit_minor_per_day": 1, "human_approval_threshold_minor": 1 } }, "effects": "May change state through PUT /api/policies. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/policies", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "actions.list", "title": "List P2P actions", "description": "List P2P action requests.", "method": "GET", "path": "/api/actions", "permission": "actions:invoke", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "state": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List P2P actions.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "limit": 1, "state": "example" }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/actions", "body": null }, "effects": "Reads state through GET /api/actions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/actions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "actions.get", "title": "Get P2P action", "description": "Get one organization-scoped P2P action request and its lifecycle details.", "method": "GET", "path": "/api/actions/{requestId}", "permission": "actions:invoke", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "requestId": "example" }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/actions/example", "body": null }, "effects": "Reads state through GET /api/actions/{requestId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/actions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "actions.request", "title": "Request P2P action", "description": "Request a P2P action.", "method": "POST", "path": "/api/actions/request", "permission": "actions:request", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "capability_id": { "type": "string", "minLength": 1 }, "idempotency_key": { "type": "string", "minLength": 1 }, "inputs": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string", "minLength": 1 } ] } }, "required": [ "capability_id", "idempotency_key" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Request P2P action.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "capability_id": "00000000-0000-4000-8000-000000000000", "idempotency_key": "example" }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/actions/request", "body": { "capability_id": "00000000-0000-4000-8000-000000000000", "idempotency_key": "example" } }, "effects": "May change state through POST /api/actions/request. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/actions/request", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "actions.respond", "title": "Respond to P2P action", "description": "Respond to a P2P action.", "method": "POST", "path": "/api/actions/{requestId}/respond", "permission": "actions:respond", "authorizationMode": "runtime", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "response": { "type": "string", "enum": [ "accepted", "quoted", "rejected", "approved" ] }, "quote": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string", "minLength": 1 } ] }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "requestId", "response" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Respond to P2P action.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "requestId": "example", "response": "accepted" }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/actions/example/respond", "body": { "requestId": "example", "response": "accepted" } }, "effects": "May change state through POST /api/actions/{requestId}/respond. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/actions/*/respond", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "actions.complete", "title": "Complete P2P action", "description": "Complete a P2P action.", "method": "POST", "path": "/api/actions/{requestId}/complete", "permission": "actions:respond", "authorizationMode": "runtime", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "result": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string", "minLength": 1 } ] } }, "required": [ "requestId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Complete P2P action.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "requestId": "example" }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/actions/example/complete", "body": { "requestId": "example" } }, "effects": "May change state through POST /api/actions/{requestId}/complete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/actions/*/complete", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "actions.dispute", "title": "Dispute P2P action", "description": "Dispute a P2P action.", "method": "POST", "path": "/api/actions/{requestId}/dispute", "permission": "actions:respond", "authorizationMode": "runtime", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Dispute P2P action.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "requestId": "example" }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/actions/example/dispute", "body": { "requestId": "example" } }, "effects": "May change state through POST /api/actions/{requestId}/dispute. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/actions/*/dispute", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "holds.release", "title": "Release P2P hold", "description": "Resolve a P2P hold to the buyer or seller and apply any required ledger counter-reversal.", "method": "POST", "path": "/api/holds/{holdId}/release", "permission": "actions:respond", "authorizationMode": "runtime", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "holdId": { "type": "string", "minLength": 1 }, "resolution": { "type": "string", "enum": [ "buyer", "seller" ] }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "holdId", "resolution" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "holdId": "example", "resolution": "buyer" }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/holds/example/release", "body": { "holdId": "example", "resolution": "buyer" } }, "effects": "May change state through POST /api/holds/{holdId}/release. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/holds/*/release", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.export", "title": "Export organization P2P data", "description": "Export the caller organization's P2P records across directory, runtime, ledger, and audit stores.", "method": "GET", "path": "/api/organizations/{organizationId}/data", "permission": "privacy:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "organizationId": "example" }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/example/data", "body": null }, "effects": "Reads state through GET /api/organizations/{organizationId}/data without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.erase", "title": "Erase organization P2P data", "description": "Erase organization-owned P2P content while retaining immutable bilateral financial records required for ledger integrity.", "method": "DELETE", "path": "/api/organizations/{organizationId}/data", "permission": "privacy:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "organizationId", "confirmation" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "organizationId": "example", "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-p2p --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/example/data", "body": null }, "effects": "May change state through DELETE /api/organizations/{organizationId}/data. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 26, "matched_actions": 20, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 6, "configured_exclusions": 3, "configuration_findings": [], "notes": [ "2 manually-declared route(s)" ] }, "runtime_contract_audit": { "status": "verified", "actions": 20, "contracts": 20, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/worker.ts" ], "authorization_sources": [ "apps/api/src/worker.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "system-apps/TopoloP2P/topolo.mobile-experience.json", "contract": { "version": "2026-06-29", "status": "approved", "mode": "native_capability", "appId": "app_topolo_p2p", "localizationNamespace": "p2p", "permissions": [ "directory:read", "ledger:read" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/capabilities", "auth": { "audience": "topolo-p2p", "scopes": [ "directory:read", "ledger:read" ] }, "routes": [ { "path": "/capabilities", "apiPath": "/api/directory/capabilities", "title": "Capabilities", "titleKey": "p2p.mobile.routes.capabilities.title", "template": "record.list", "dataSource": "p2p.capabilities.list" }, { "path": "/connections", "apiPath": "/api/connections", "title": "Connections", "titleKey": "p2p.mobile.routes.connections.title", "template": "record.list", "dataSource": "p2p.connections.list" }, { "path": "/ledger", "apiPath": "/api/ledger", "title": "Ledger", "titleKey": "p2p.mobile.routes.ledger.title", "template": "record.list", "dataSource": "p2p.ledger.list" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "ALL", "path": "*", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/health", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/health", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/directory/capabilities", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/p2p/internal/capabilities/sync", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/widget", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/connections", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/ledger", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/settlements/preview", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/settlements/create", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/policies", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/actions", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/actions/request", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" } ], "ui_routes": [ { "path": "/actions/${encodeURIComponent(requestId)}", "source_path": "system-apps/TopoloP2P/apps/api/src/actions.ts" }, { "path": "/actions/${encodeURIComponent(action.request_id)}", "source_path": "system-apps/TopoloP2P/apps/api/src/actions.ts" }, { "path": "/connections", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "path": "/actions/${encodeURIComponent(hold.request_id)}", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "path": "/settlements", "source_path": "system-apps/TopoloP2P/apps/api/src/worker.ts" }, { "path": "/dashboard", "source_path": "system-apps/TopoloP2P/apps/web/src/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/topolo-p2p", "internal/apps/topolo-p2p", "internal/platform/p2p-protocol", "internal/platform/p2p-ledger-and-settlement" ], "present_paths": [ "applications/topolo-p2p", "internal/apps/topolo-p2p", "internal/platform/p2p-protocol", "internal/platform/p2p-ledger-and-settlement" ], "missing_paths": [], "human_reference": "/systems/topolo-p2p", "machine_reference": "/machine/systems/topolo-p2p.json", "action_examples": 20, "action_schemas": 20 }, "source_findings": [] }, "topolo-pay": { "id": "topolo-pay", "name": "Topolo Pay", "slug": "topolo-pay", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloPay" ], "source_revisions": [ { "source_path": "apps/TopoloPay", "repository": "apps/TopoloPay", "revision": "f7f8d29b3072c92900c77c0b64022b013d1e02f8", "ref": "origin/staging" } ], "source_counts": { "source_files": 102, "test_files": 52, "test_cases": 0, "migration_files": 0, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 58, "mobile_contracts": 1, "notifications": 17, "package_manifests": 2, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloPay/topolo.app.json", "service_slug": "topolo-pay", "name": "topolo-pay", "app_id": "app_topolo_pay", "compatibility_date": "2026-05-01", "primary_target": "web", "environments": [ "development", "production", "staging" ], "targets": [ { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/index.ts", "worker_name": "topolo-pay-api", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "API_VERSION", "AUTH_API_URL", "ENVIRONMENT", "NEXUS_GATEWAY_URL", "NODE_ENV", "PAY_APP_URL", "TOPOLO_NOTIFY_URL", "TOPOLO_P2P_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "PAY_CORE_DB", "target": null }, { "kind": "d1", "binding": "PAY_LEDGER_DB", "target": null }, { "kind": "d1", "binding": "PAY_P2P_DB", "target": null }, { "kind": "d1", "binding": "PAY_WEBHOOK_DB", "target": null }, { "kind": "d1", "binding": "PAY_ANALYTICS_DB", "target": null }, { "kind": "d1", "binding": "PAY_USAGE_DB", "target": null }, { "kind": "d1", "binding": "PAY_AUDIT_DB", "target": null }, { "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 } ] }, { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-pay", "subdomain": "pay", "healthcheck_path": "/health", "variable_names": [ "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null } ] } ], "notifications": [ "billing.dunning.day14", "billing.dunning.day3", "billing.dunning.day7", "billing.invoice.created", "billing.invoice.paid", "billing.payment.failed", "billing.payment.succeeded", "billing.subscription.cancel_requested", "billing.subscription.cancelled", "billing.subscription.reactivated", "billing.subscription.renewal_upcoming", "billing.subscription.renewed", "billing.trial.ended", "billing.trial.ending_soon", "billing.winback.followup", "pay.payout.failed", "pay.settlement.completed" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_pay", "events": [ { "type": "billing.dunning.day14", "version": 1, "description": "Invoice unpaid for 14 days", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "high" }, "severity": { "const": "warning" }, "category": { "const": "billing" }, "object_type": { "const": "invoice" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Invoice unpaid for 14 days", "body": "Invoice unpaid for 14 days.", "surface": "notification", "priority": "high", "severity": "warning", "category": "billing", "object_type": "invoice", "object_id": "invoice_123", "thread_key": "billing:invoice:invoice_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:dunning-day14):" } }, { "type": "billing.dunning.day3", "version": 1, "description": "Invoice unpaid for 3 days", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "high" }, "severity": { "const": "warning" }, "category": { "const": "billing" }, "object_type": { "const": "invoice" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Invoice unpaid for 3 days", "body": "Invoice unpaid for 3 days.", "surface": "notification", "priority": "high", "severity": "warning", "category": "billing", "object_type": "invoice", "object_id": "invoice_123", "thread_key": "billing:invoice:invoice_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:dunning-day3):" } }, { "type": "billing.dunning.day7", "version": 1, "description": "Invoice unpaid for 7 days", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "high" }, "severity": { "const": "warning" }, "category": { "const": "billing" }, "object_type": { "const": "invoice" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Invoice unpaid for 7 days", "body": "Invoice unpaid for 7 days.", "surface": "notification", "priority": "high", "severity": "warning", "category": "billing", "object_type": "invoice", "object_id": "invoice_123", "thread_key": "billing:invoice:invoice_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:dunning-day7):" } }, { "type": "billing.invoice.created", "version": 1, "description": "Subscription invoice created", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "info" }, "category": { "const": "billing" }, "object_type": { "const": "invoice" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Subscription invoice created", "body": "Subscription invoice created.", "surface": "notification", "priority": "normal", "severity": "info", "category": "billing", "object_type": "invoice", "object_id": "invoice_123", "thread_key": "billing:invoice:invoice_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:invoice-created):" } }, { "type": "billing.invoice.paid", "version": 1, "description": "Subscription invoice paid", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "success" }, "category": { "const": "billing" }, "object_type": { "const": "invoice" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Subscription invoice paid", "body": "Subscription invoice paid.", "surface": "notification", "priority": "normal", "severity": "success", "category": "billing", "object_type": "invoice", "object_id": "invoice_123", "thread_key": "billing:invoice:invoice_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:invoice-paid):" } }, { "type": "billing.payment.failed", "version": 1, "description": "Payment failed", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "high" }, "severity": { "const": "critical" }, "category": { "const": "payments" }, "object_type": { "const": "payment" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Payment failed", "body": "Payment failed.", "surface": "notification", "priority": "high", "severity": "critical", "category": "payments", "object_type": "payment", "object_id": "payment_123", "thread_key": "payments:payment:payment_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:(?:invoice-)?payment-failed|payment-failed):" } }, { "type": "billing.payment.succeeded", "version": 1, "description": "Payment succeeded", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "success" }, "category": { "const": "payments" }, "object_type": { "const": "payment" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Payment succeeded", "body": "Payment succeeded.", "surface": "notification", "priority": "normal", "severity": "success", "category": "payments", "object_type": "payment", "object_id": "payment_123", "thread_key": "payments:payment:payment_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:payment-succeeded):" } }, { "type": "billing.subscription.cancel_requested", "version": 1, "description": "Subscription cancellation requested", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "warning" }, "category": { "const": "billing" }, "object_type": { "const": "subscription" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Subscription cancellation requested", "body": "Subscription cancellation requested.", "surface": "notification", "priority": "normal", "severity": "warning", "category": "billing", "object_type": "subscription", "object_id": "subscription_123", "thread_key": "billing:subscription:subscription_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:cancel-requested):" } }, { "type": "billing.subscription.cancelled", "version": 1, "description": "Subscription cancelled", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "warning" }, "category": { "const": "billing" }, "object_type": { "const": "subscription" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Subscription cancelled", "body": "Subscription cancelled.", "surface": "notification", "priority": "normal", "severity": "warning", "category": "billing", "object_type": "subscription", "object_id": "subscription_123", "thread_key": "billing:subscription:subscription_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:cancelled):" } }, { "type": "billing.subscription.reactivated", "version": 1, "description": "Subscription reactivated", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "success" }, "category": { "const": "billing" }, "object_type": { "const": "subscription" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Subscription reactivated", "body": "Subscription reactivated.", "surface": "notification", "priority": "normal", "severity": "success", "category": "billing", "object_type": "subscription", "object_id": "subscription_123", "thread_key": "billing:subscription:subscription_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:reactivated):" } }, { "type": "billing.subscription.renewal_upcoming", "version": 1, "description": "Subscription renewal upcoming", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "info" }, "category": { "const": "billing" }, "object_type": { "const": "subscription" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Subscription renewal upcoming", "body": "Subscription renewal upcoming.", "surface": "notification", "priority": "normal", "severity": "info", "category": "billing", "object_type": "subscription", "object_id": "subscription_123", "thread_key": "billing:subscription:subscription_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:renewal-upcoming):" } }, { "type": "billing.subscription.renewed", "version": 1, "description": "Subscription renewed", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "success" }, "category": { "const": "billing" }, "object_type": { "const": "subscription" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Subscription renewed", "body": "Subscription renewed.", "surface": "notification", "priority": "normal", "severity": "success", "category": "billing", "object_type": "subscription", "object_id": "subscription_123", "thread_key": "billing:subscription:subscription_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:renewed):" } }, { "type": "billing.trial.ended", "version": 1, "description": "Subscription trial ended", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "info" }, "category": { "const": "billing" }, "object_type": { "const": "subscription" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Subscription trial ended", "body": "Subscription trial ended.", "surface": "notification", "priority": "normal", "severity": "info", "category": "billing", "object_type": "subscription", "object_id": "subscription_123", "thread_key": "billing:subscription:subscription_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:trial-ended):" } }, { "type": "billing.trial.ending_soon", "version": 1, "description": "Subscription trial ending soon", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "warning" }, "category": { "const": "billing" }, "object_type": { "const": "subscription" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Subscription trial ending soon", "body": "Subscription trial ending soon.", "surface": "notification", "priority": "normal", "severity": "warning", "category": "billing", "object_type": "subscription", "object_id": "subscription_123", "thread_key": "billing:subscription:subscription_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:trial-ending):" } }, { "type": "billing.winback.followup", "version": 1, "description": "Cancelled subscription follow-up", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "info" }, "category": { "const": "billing" }, "object_type": { "const": "subscription" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Cancelled subscription follow-up", "body": "Cancelled subscription follow-up.", "surface": "notification", "priority": "normal", "severity": "info", "category": "billing", "object_type": "subscription", "object_id": "subscription_123", "thread_key": "billing:subscription:subscription_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:winback):" } }, { "type": "pay.payout.failed", "version": 1, "description": "Connected-account payout failed", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "high" }, "severity": { "const": "critical" }, "category": { "const": "payments" }, "object_type": { "const": "payout" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Connected-account payout failed", "body": "Connected-account payout failed.", "surface": "notification", "priority": "high", "severity": "critical", "category": "payments", "object_type": "payout", "object_id": "payout_123", "thread_key": "payments:payout:payout_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:payout-failed):" } }, { "type": "pay.settlement.completed", "version": 1, "description": "Inter-organization settlement completed", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "title", "body", "surface", "priority", "severity", "category", "object_type", "object_id", "thread_key", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "success" }, "category": { "const": "payments" }, "object_type": { "const": "settlement" }, "object_id": { "type": "string", "minLength": 1 }, "thread_key": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "amount_minor": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "action_url": { "type": "string", "format": "uri" } } }, "examples": [ { "title": "Inter-organization settlement completed", "body": "Inter-organization settlement completed.", "surface": "notification", "priority": "normal", "severity": "success", "category": "payments", "object_type": "settlement", "object_id": "settlement_123", "thread_key": "payments:settlement:settlement_123", "occurred_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^topolo-pay:(?:settlement-completed):" } } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "dashboard:read", "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-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "analytics.get", "title": "Get Pay analytics", "description": "Get Pay analytics.", "method": "GET", "path": "/api/admin/analytics", "permission": "analytics:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "dateFrom": { "type": "string", "minLength": 1 }, "dateTo": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get Pay analytics.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "dateFrom": "example", "dateTo": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/analytics", "body": null }, "effects": "Reads state through GET /api/admin/analytics without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/analytics", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "transactions.list", "title": "List transactions", "description": "List Pay transactions.", "method": "GET", "path": "/api/admin/transactions", "permission": "transactions:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }, "search": { "type": "string", "minLength": 1 }, "merchant": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "method": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "dateFrom": { "type": "string", "minLength": 1 }, "dateTo": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List transactions.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "page": 1, "limit": 1, "search": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/transactions", "body": null }, "effects": "Reads state through GET /api/admin/transactions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/transactions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "customers.list", "title": "List customers", "description": "List Pay customers.", "method": "GET", "path": "/api/admin/customers", "permission": "customers:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List customers.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "search": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/customers", "body": null }, "effects": "Reads state through GET /api/admin/customers without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/customers", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "merchants.list", "title": "Merchants List", "description": "Call GET /api/merchants.", "method": "GET", "path": "/api/merchants", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Merchants List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "public", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/merchants", "body": null }, "effects": "Reads state through GET /api/merchants without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/merchants", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "subscriptions.checkout", "title": "Create subscription checkout", "description": "Create a subscription checkout session.", "method": "POST", "path": "/api/subscriptions/checkout", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "priceId": { "type": "string", "minLength": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "customerEmail": { "type": "string", "minLength": 1 }, "customerName": { "type": "string", "minLength": 1 }, "externalSystem": { "type": "string", "minLength": 1 }, "externalUserId": { "type": "string", "minLength": 1 }, "externalOrgId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "successUrl": { "type": "string", "minLength": 1 }, "cancelUrl": { "type": "string", "minLength": 1 }, "trialPeriodDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "allowPromotionCodes": { "type": "boolean" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "inlinePrice": { "type": "object", "properties": { "productName": { "type": "string", "minLength": 1 }, "unitAmount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 1 }, "interval": { "type": "string", "enum": [ "day", "week", "month", "year" ] } }, "required": [ "productName", "unitAmount", "currency", "interval" ], "additionalProperties": false } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create subscription checkout.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "priceId": "example", "quantity": 1, "customerEmail": "user@example.com" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/subscriptions/checkout", "body": { "priceId": "example", "quantity": 1, "customerEmail": "user@example.com" } }, "effects": "May change state through POST /api/subscriptions/checkout. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/subscriptions/checkout", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pricing_plans.list", "title": "List pricing plans", "description": "List platform pricing plans.", "method": "GET", "path": "/api/pricing-plans", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "developerOrgId": { "type": "string", "minLength": 1 }, "includeInactive": { "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List pricing plans.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "appId": "example", "developerOrgId": "example", "includeInactive": "true" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/pricing-plans", "body": null }, "effects": "Reads state through GET /api/pricing-plans without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/pricing-plans", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "p2p.settlements.create", "title": "Create P2P settlement", "description": "Create a TopoloPay P2P settlement.", "method": "POST", "path": "/api/p2p/settlements", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "batch_id": { "type": "string", "minLength": 1 }, "buyer_org_id": { "type": "string", "minLength": 1 }, "seller_org_id": { "type": "string", "minLength": 1 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "total_minor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "trigger": { "type": "string", "enum": [ "threshold", "schedule", "manual", "invoice", "delivery" ] }, "line_items": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "entry_id": { "type": "string", "minLength": 1 }, "request_id": { "type": "string", "minLength": 1 }, "capability_id": { "type": "string", "minLength": 1 }, "pricing_component": { "type": "string", "minLength": 1 }, "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "audit_correlation_id": { "type": "string", "minLength": 1 } }, "required": [ "entry_id", "request_id", "capability_id", "pricing_component", "amount_minor", "audit_correlation_id" ], "additionalProperties": false } } }, "required": [ "batch_id", "buyer_org_id", "seller_org_id", "currency", "total_minor", "trigger", "line_items" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create P2P settlement.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "batch_id": "00000000-0000-4000-8000-000000000000", "buyer_org_id": "00000000-0000-4000-8000-000000000000", "seller_org_id": "00000000-0000-4000-8000-000000000000", "currency": "USD", "total_minor": 1, "trigger": "threshold", "line_items": [ { "entry_id": "00000000-0000-4000-8000-000000000000", "request_id": "00000000-0000-4000-8000-000000000000", "capability_id": "00000000-0000-4000-8000-000000000000", "pricing_component": "example", "amount_minor": 1, "audit_correlation_id": "00000000-0000-4000-8000-000000000000" } ] }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/p2p/settlements", "body": { "batch_id": "00000000-0000-4000-8000-000000000000", "buyer_org_id": "00000000-0000-4000-8000-000000000000", "seller_org_id": "00000000-0000-4000-8000-000000000000", "currency": "USD", "total_minor": 1, "trigger": "threshold", "line_items": [ { "entry_id": "00000000-0000-4000-8000-000000000000", "request_id": "00000000-0000-4000-8000-000000000000", "capability_id": "00000000-0000-4000-8000-000000000000", "pricing_component": "example", "amount_minor": 1, "audit_correlation_id": "00000000-0000-4000-8000-000000000000" } ] } }, "effects": "May change state through POST /api/p2p/settlements. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/p2p/settlements", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "p2p.settlements.complete", "title": "Complete P2P settlement", "description": "Persist a completed TopoloPay P2P settlement and publish its notification transition.", "method": "POST", "path": "/api/p2p/settlements/{batchId}/complete", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "batchId": { "type": "string", "minLength": 1 }, "provider_status": { "type": "string", "minLength": 1 } }, "required": [ "batchId", "provider_status" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Complete P2P settlement.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "batchId": "example", "provider_status": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/p2p/settlements/example/complete", "body": { "batchId": "example", "provider_status": "example" } }, "effects": "May change state through POST /api/p2p/settlements/{batchId}/complete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/p2p/settlements/*/complete", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "crypto_payments.create", "title": "Create crypto payment", "description": "Create a TopoloPay crypto payment.", "method": "POST", "path": "/pay/crypto", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orderId": { "type": "string", "minLength": 1 }, "amountCents": { "type": "number", "exclusiveMinimum": 0 }, "currency": { "type": "string", "minLength": 1 }, "merchantId": { "type": "string", "minLength": 1 }, "customerEmail": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "redirectUrl": { "type": "string", "minLength": 1 }, "cancelUrl": { "type": "string", "minLength": 1 } }, "required": [ "orderId", "amountCents", "currency", "merchantId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create crypto payment.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "orderId": "example", "amountCents": 1, "currency": "USD", "merchantId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/pay/crypto", "body": { "orderId": "example", "amountCents": 1, "currency": "USD", "merchantId": "example" } }, "effects": "May change state through POST /pay/crypto. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /pay/crypto", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "crypto_payments.status.get", "title": "Get crypto payment status", "description": "Get TopoloPay crypto payment status.", "method": "GET", "path": "/pay/crypto/{chargeId}/status", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "chargeId": { "type": "string", "minLength": 1 } }, "required": [ "chargeId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get crypto payment status.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "chargeId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/pay/crypto/example/status", "body": null }, "effects": "Reads state through GET /pay/crypto/{chargeId}/status without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /pay/crypto/*/status", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "merchants.fees.get", "title": "Get merchant fees", "description": "Get TopoloPay merchant fees.", "method": "GET", "path": "/api/merchants/{merchantId}/fees", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "merchantId": { "type": "string", "minLength": 1 } }, "required": [ "merchantId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get merchant fees.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "public", "documentation": { "example_input": { "merchantId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/merchants/example/fees", "body": null }, "effects": "Reads state through GET /api/merchants/{merchantId}/fees without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/merchants/*/fees", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "subscriptions.payment_intent.create", "title": "Create subscription payment intent", "description": "Create a subscription payment intent.", "method": "POST", "path": "/api/subscriptions/payment-intent", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "priceId": { "type": "string", "minLength": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "customerEmail": { "type": "string", "minLength": 1 }, "customerName": { "type": "string", "minLength": 1 }, "externalSystem": { "type": "string", "minLength": 1 }, "externalUserId": { "type": "string", "minLength": 1 }, "externalOrgId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "trialPeriodDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "inlinePrice": { "type": "object", "properties": { "productName": { "type": "string", "minLength": 1 }, "unitAmount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 1 }, "interval": { "type": "string", "enum": [ "day", "week", "month", "year" ] } }, "required": [ "productName", "unitAmount", "currency", "interval" ], "additionalProperties": false } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create subscription payment intent.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "priceId": "example", "quantity": 1, "customerEmail": "user@example.com" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/subscriptions/payment-intent", "body": { "priceId": "example", "quantity": 1, "customerEmail": "user@example.com" } }, "effects": "May change state through POST /api/subscriptions/payment-intent. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/subscriptions/payment-intent", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "subscriptions.by_external.get", "title": "Get subscription by external user", "description": "Get a subscription by external user id.", "method": "GET", "path": "/api/subscriptions/by-external/{userId}", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "system": { "type": "string", "minLength": 1 }, "includeAll": { "type": "string", "enum": [ "true", "false" ] } }, "required": [ "userId", "system" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get subscription by external user.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "userId": "example", "system": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/subscriptions/by-external/example", "body": null }, "effects": "Reads state through GET /api/subscriptions/by-external/{userId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/subscriptions/by-external/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "subscriptions.by_checkout_session.get", "title": "Get subscription by checkout session", "description": "Get a subscription by checkout session.", "method": "GET", "path": "/api/subscriptions/by-checkout-session/{sessionId}", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "sessionId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get subscription by checkout session.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "sessionId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/subscriptions/by-checkout-session/example", "body": null }, "effects": "Reads state through GET /api/subscriptions/by-checkout-session/{sessionId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/subscriptions/by-checkout-session/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "subscriptions.bind_external", "title": "Bind external subscription", "description": "Bind external subscription metadata.", "method": "POST", "path": "/api/subscriptions/{id}/bind-external", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "externalSystem": { "type": "string", "minLength": 1 }, "externalOrgId": { "type": "string", "minLength": 1 }, "externalUserId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Bind external subscription.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/subscriptions/00000000-0000-4000-8000-000000000000/bind-external", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/subscriptions/{id}/bind-external. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/subscriptions/*/bind-external", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "subscriptions.get", "title": "Get subscription", "description": "Get a TopoloPay subscription.", "method": "GET", "path": "/api/subscriptions/{id}", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get subscription.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/subscriptions/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/subscriptions/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/subscriptions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pricing_plans.create", "title": "Create pricing plan", "description": "Create a TopoloPay pricing plan.", "method": "POST", "path": "/api/pricing-plans", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "appId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "developerOrgId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1 }, "pricingModel": { "type": "string", "enum": [ "free", "included", "flat", "per_seat", "per_seat_tiered", "metered", "metered_tiered", "flat_plus_metered", "one_time", "sales_led" ] }, "unitLabel": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "billingCurrency": { "type": "string", "minLength": 1 }, "billingInterval": { "anyOf": [ { "type": "string", "enum": [ "day", "week", "month", "year" ] }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "revShareBps": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "pricingDetails": { "type": "object", "properties": { "productName": { "type": "string", "minLength": 1 }, "unitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "upTo": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "const": "inf" } ] }, "unitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "flatAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "upTo" ], "additionalProperties": false } }, "tiersMode": { "type": "string", "enum": [ "graduated", "volume" ] }, "meteredUnitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "flatBaseAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "required": [ "id", "displayName", "pricingModel" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create pricing plan.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "displayName": "example", "pricingModel": "free" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/pricing-plans", "body": { "id": "00000000-0000-4000-8000-000000000000", "displayName": "example", "pricingModel": "free" } }, "effects": "May change state through POST /api/pricing-plans. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/pricing-plans", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pricing_plans.bulk_create", "title": "Bulk create pricing plans", "description": "Bulk create TopoloPay pricing plans.", "method": "POST", "path": "/api/pricing-plans/bulk-register", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "plans": { "minItems": 1, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "plans" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Bulk create pricing plans.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "plans": [ {} ] }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/pricing-plans/bulk-register", "body": { "plans": [ {} ] } }, "effects": "May change state through POST /api/pricing-plans/bulk-register. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/pricing-plans/bulk-register", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pricing_plans.by_app.list", "title": "List pricing by app", "description": "List TopoloPay pricing plans by app.", "method": "GET", "path": "/api/pricing-plans/by-app/{appId}", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List pricing by app.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "appId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/pricing-plans/by-app/example", "body": null }, "effects": "Reads state through GET /api/pricing-plans/by-app/{appId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/pricing-plans/by-app/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "pricing_plans.get", "title": "Get pricing plan", "description": "Get a TopoloPay pricing plan.", "method": "GET", "path": "/api/pricing-plans/{id}", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get pricing plan.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/pricing-plans/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/pricing-plans/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/pricing-plans/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "platform_pricing.get", "title": "Get platform pricing", "description": "Get Topolo platform pricing.", "method": "GET", "path": "/api/platform-pricing", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get platform pricing.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "public", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/platform-pricing", "body": null }, "effects": "Reads state through GET /api/platform-pricing without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/platform-pricing", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "platform_pricing.update", "title": "Update platform pricing", "description": "Update Topolo platform pricing.", "method": "PUT", "path": "/api/platform-pricing", "requiresConfirmation": true, "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": { "type": "array", "items": { "type": "object", "properties": { "upTo": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "const": "inf" } ] }, "unitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "upTo", "unitAmountCents" ], "additionalProperties": false } } }, "required": [ "planId", "monthlyCentsPerSeat" ], "additionalProperties": false }, "includedFreeInBase": { "type": "array", "items": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "headline": { "type": "string", "minLength": 1 }, "marketingPath": { "type": "string", "minLength": 1 } }, "required": [ "appId", "headline" ], "additionalProperties": false } }, "platformCapabilities": { "type": "array", "items": { "type": "string" } }, "platformTagline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schemaVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "editorUserId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update platform pricing.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "base": { "planId": "example", "monthlyCentsPerSeat": 1 }, "includedFreeInBase": [ { "appId": "example", "headline": "example" } ], "platformCapabilities": [ "example" ] }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/platform-pricing", "body": { "base": { "planId": "example", "monthlyCentsPerSeat": 1 }, "includedFreeInBase": [ { "appId": "example", "headline": "example" } ], "platformCapabilities": [ "example" ] } }, "effects": "May change state through PUT /api/platform-pricing. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/platform-pricing", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "subscription_items.list", "title": "List subscription items", "description": "List subscription items.", "method": "GET", "path": "/api/subscriptions/{subId}/items", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subId": { "type": "string", "minLength": 1 } }, "required": [ "subId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List subscription items.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "subId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/subscriptions/example/items", "body": null }, "effects": "Reads state through GET /api/subscriptions/{subId}/items without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/subscriptions/*/items", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "subscription_items.create", "title": "Create subscription item", "description": "Create a subscription item.", "method": "POST", "path": "/api/subscriptions/{subId}/items", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subId": { "type": "string", "minLength": 1 }, "pricingPlanId": { "type": "string", "minLength": 1 }, "quantity": { "type": "number", "minimum": 0 }, "itemKind": { "type": "string", "enum": [ "base", "app" ] } }, "required": [ "subId", "pricingPlanId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create subscription item.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "subId": "example", "pricingPlanId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/subscriptions/example/items", "body": { "subId": "example", "pricingPlanId": "example" } }, "effects": "May change state through POST /api/subscriptions/{subId}/items. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/subscriptions/*/items", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "subscription_items.update", "title": "Update subscription item", "description": "Update a subscription item.", "method": "PATCH", "path": "/api/subscriptions/{subId}/items/{itemId}", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subId": { "type": "string", "minLength": 1 }, "itemId": { "type": "string", "minLength": 1 }, "quantity": { "type": "number", "minimum": 0 } }, "required": [ "subId", "itemId", "quantity" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update subscription item.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "subId": "example", "itemId": "example", "quantity": 1 }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/subscriptions/example/items/example", "body": { "subId": "example", "itemId": "example", "quantity": 1 } }, "effects": "May change state through PATCH /api/subscriptions/{subId}/items/{itemId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/subscriptions/*/items/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "subscription_items.delete", "title": "Delete subscription item", "description": "Delete a subscription item.", "method": "DELETE", "path": "/api/subscriptions/{subId}/items/{itemId}", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subId": { "type": "string", "minLength": 1 }, "itemId": { "type": "string", "minLength": 1 } }, "required": [ "subId", "itemId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete subscription item.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "subId": "example", "itemId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/subscriptions/example/items/example", "body": null }, "effects": "May change state through DELETE /api/subscriptions/{subId}/items/{itemId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/subscriptions/*/items/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organization_subscription_items.list", "title": "List organization subscription items", "description": "List organization subscription items.", "method": "GET", "path": "/api/subscriptions/by-external-org/{orgId}/items", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "system": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "system" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List organization subscription items.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "orgId": "example", "system": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/subscriptions/by-external-org/example/items", "body": null }, "effects": "Reads state through GET /api/subscriptions/by-external-org/{orgId}/items without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/subscriptions/by-external-org/*/items", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organization_subscriptions.summary.get", "title": "Get organization subscription summary", "description": "Get organization subscription summary.", "method": "GET", "path": "/api/subscriptions/by-external-org/{orgId}/summary", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "system": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get organization subscription summary.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "orgId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/subscriptions/by-external-org/example/summary", "body": null }, "effects": "Reads state through GET /api/subscriptions/by-external-org/{orgId}/summary without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/subscriptions/by-external-org/*/summary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organization_subscriptions.base_seat_count.update", "title": "Update base seat count", "description": "Update organization subscription base seat count.", "method": "POST", "path": "/api/subscriptions/by-external-org/{orgId}/base-seat-count", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "system": { "type": "string", "minLength": 1 }, "seatCount": { "type": "number", "minimum": 0 } }, "required": [ "orgId", "system", "seatCount" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update base seat count.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "orgId": "example", "system": "example", "seatCount": 1 }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/subscriptions/by-external-org/example/base-seat-count", "body": { "orgId": "example", "system": "example", "seatCount": 1 } }, "effects": "May change state through POST /api/subscriptions/by-external-org/{orgId}/base-seat-count. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/subscriptions/by-external-org/*/base-seat-count", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "connect.onboard", "title": "Start Connect onboarding", "description": "Start TopoloPay Connect onboarding.", "method": "POST", "path": "/admin/connect/onboard", "permission": "merchants:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "merchantId": { "type": "string", "minLength": 1 }, "returnUrl": { "type": "string", "minLength": 1 }, "refreshUrl": { "type": "string", "minLength": 1 }, "email": { "type": "string", "minLength": 1 } }, "required": [ "merchantId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Start Connect onboarding.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "merchantId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/admin/connect/onboard", "body": { "merchantId": "example" } }, "effects": "May change state through POST /admin/connect/onboard. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /admin/connect/onboard", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "connect.status.get", "title": "Get Connect status", "description": "Get TopoloPay Connect status.", "method": "GET", "path": "/admin/connect/status", "permission": "merchants:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "merchantId": { "type": "string", "minLength": 1 } }, "required": [ "merchantId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get Connect status.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "merchantId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/admin/connect/status", "body": null }, "effects": "Reads state through GET /admin/connect/status without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /admin/connect/status", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "connect.dashboard_link.create", "title": "Create Connect dashboard link", "description": "Create a TopoloPay Connect dashboard link.", "method": "POST", "path": "/admin/connect/dashboard-link", "permission": "merchants:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "merchantId": { "type": "string", "minLength": 1 } }, "required": [ "merchantId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create Connect dashboard link.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "merchantId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/admin/connect/dashboard-link", "body": { "merchantId": "example" } }, "effects": "May change state through POST /admin/connect/dashboard-link. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /admin/connect/dashboard-link", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.transactions.results.list", "title": "List transaction results", "description": "List TopoloPay transaction search results.", "method": "GET", "path": "/admin/transactions/results", "permission": "transactions:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }, "search": { "type": "string", "minLength": 1 }, "merchant": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "method": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "dateFrom": { "type": "string", "minLength": 1 }, "dateTo": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List transaction results.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "page": 1, "limit": 1, "search": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/admin/transactions/results", "body": null }, "effects": "Reads state through GET /admin/transactions/results without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /admin/transactions/results", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.transactions.search", "title": "Search transactions", "description": "Search TopoloPay transactions.", "method": "GET", "path": "/admin/transactions/search", "permission": "transactions:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }, "search": { "type": "string", "minLength": 1 }, "merchant": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "method": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "dateFrom": { "type": "string", "minLength": 1 }, "dateTo": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Search transactions.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "page": 1, "limit": 1, "search": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/admin/transactions/search", "body": null }, "effects": "Reads state through GET /admin/transactions/search without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /admin/transactions/search", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.customers.search", "title": "Search customers", "description": "Search TopoloPay customers.", "method": "GET", "path": "/admin/customers/search", "permission": "customers:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "customerSearch": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Search customers.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "customerSearch": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/admin/customers/search", "body": null }, "effects": "Reads state through GET /admin/customers/search without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /admin/customers/search", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.customers.history.get", "title": "Get customer history", "description": "Get TopoloPay customer history.", "method": "GET", "path": "/api/admin/customers/{email}/history", "permission": "customers:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "minLength": 1 } }, "required": [ "email" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get customer history.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "email": "user@example.com" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/customers/user%40example.com/history", "body": null }, "effects": "Reads state through GET /api/admin/customers/{email}/history without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/customers/*/history", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.audit.list", "title": "List audit logs", "description": "List TopoloPay audit logs.", "method": "GET", "path": "/api/admin/audit", "permission": "audit:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }, "action": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List audit logs.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "page": 1, "limit": 1, "action": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/audit", "body": null }, "effects": "Reads state through GET /api/admin/audit without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/audit", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.export.transactions", "title": "Export transactions", "description": "Export TopoloPay transactions.", "method": "GET", "path": "/api/admin/export", "permission": "reports:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "format": { "type": "string", "enum": [ "csv" ] }, "type": { "type": "string", "enum": [ "transactions", "reconciliation", "summary" ] }, "search": { "type": "string", "minLength": 1 }, "merchant": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "method": { "type": "string", "minLength": 1 }, "dateFrom": { "type": "string", "minLength": 1 }, "dateTo": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Export transactions.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "format": "csv", "type": "transactions", "search": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/export", "body": null }, "effects": "Reads state through GET /api/admin/export without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/export", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "orders.create", "title": "Orders Create", "description": "Call POST /order.", "method": "POST", "path": "/order", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orderId": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 1 }, "merchantId": { "type": "string", "minLength": 1 }, "venueId": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "customer": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "customerEmail": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "receipt_email": { "type": "string", "minLength": 1 }, "statement_descriptor": { "type": "string", "minLength": 1 } }, "required": [ "orderId", "amount", "currency", "merchantId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Orders Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "orderId": "example", "amount": 1, "currency": "USD", "merchantId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/order", "body": { "orderId": "example", "amount": 1, "currency": "USD", "merchantId": "example" } }, "effects": "May change state through POST /order. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /order", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "orders.cancel", "title": "Orders Cancel", "description": "Call POST /order/{paymentId}/cancel.", "method": "POST", "path": "/order/{paymentId}/cancel", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "paymentId": { "type": "string", "minLength": 1 } }, "required": [ "paymentId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Orders Cancel.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "paymentId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/order/example/cancel", "body": { "paymentId": "example" } }, "effects": "May change state through POST /order/{paymentId}/cancel. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /order/*/cancel", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "payment.status.get", "title": "Payment Status Get", "description": "Call GET /payment/{sessionId}/status.", "method": "GET", "path": "/payment/{sessionId}/status", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "sessionId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Payment Status Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "sessionId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/payment/example/status", "body": null }, "effects": "Reads state through GET /payment/{sessionId}/status without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /payment/*/status", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.transactions.page.list", "title": "Admin Transactions Page List", "description": "Call GET /admin/transactions.", "method": "GET", "path": "/admin/transactions", "permission": "transactions:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }, "search": { "type": "string", "minLength": 1 }, "merchant": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "method": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "dateFrom": { "type": "string", "minLength": 1 }, "dateTo": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Admin Transactions Page List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "page": 1, "limit": 1, "search": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/admin/transactions", "body": null }, "effects": "Reads state through GET /admin/transactions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /admin/transactions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.customers.page.list", "title": "Admin Customers Page List", "description": "Call GET /admin/customers.", "method": "GET", "path": "/admin/customers", "permission": "customers:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Admin Customers Page List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/admin/customers", "body": null }, "effects": "Reads state through GET /admin/customers without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /admin/customers", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.customers.list", "title": "Admin Customers List", "description": "Call GET /admin/customers/list.", "method": "GET", "path": "/admin/customers/list", "permission": "customers:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Admin Customers List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/admin/customers/list", "body": null }, "effects": "Reads state through GET /admin/customers/list without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /admin/customers/list", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.audit.page.get", "title": "Admin Audit Page Get", "description": "Call GET /admin/audit.", "method": "GET", "path": "/admin/audit", "permission": "audit:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Admin Audit Page Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/admin/audit", "body": null }, "effects": "Reads state through GET /admin/audit without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /admin/audit", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.audit.logs.list", "title": "Admin Audit Logs List", "description": "Call GET /admin/audit/logs.", "method": "GET", "path": "/admin/audit/logs", "permission": "audit:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "auditAction": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Admin Audit Logs List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "page": 1, "auditAction": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/admin/audit/logs", "body": null }, "effects": "Reads state through GET /admin/audit/logs without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /admin/audit/logs", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.export.transactions_page", "title": "Admin Export Transactions Page", "description": "Call GET /admin/export/transactions.", "method": "GET", "path": "/admin/export/transactions", "permission": "reports:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "format": { "type": "string", "enum": [ "csv" ] }, "type": { "type": "string", "enum": [ "transactions", "reconciliation", "summary" ] }, "search": { "type": "string", "minLength": 1 }, "merchant": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "method": { "type": "string", "minLength": 1 }, "dateFrom": { "type": "string", "minLength": 1 }, "dateTo": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Admin Export Transactions Page.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "format": "csv", "type": "transactions", "search": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/admin/export/transactions", "body": null }, "effects": "Reads state through GET /admin/export/transactions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /admin/export/transactions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.transaction.get", "title": "Admin Transaction Get", "description": "Call GET /api/admin/transaction/{id}.", "method": "GET", "path": "/api/admin/transaction/{id}", "permission": "transactions:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Admin Transaction Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/transaction/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/admin/transaction/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/transaction/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.refund.create", "title": "Admin Refund Create", "description": "Call POST /api/admin/refund/{id}.", "method": "POST", "path": "/api/admin/refund/{id}", "permission": "transactions:refund", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "amount": { "type": "number", "exclusiveMinimum": 0 }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "id", "amount", "reason" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Admin Refund Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "amount": 1, "reason": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/admin/refund/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000", "amount": 1, "reason": "example" } }, "effects": "May change state through POST /api/admin/refund/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/admin/refund/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.invoices.list", "title": "List invoices", "description": "List Stripe invoices visible to the current organization or platform operator.", "method": "GET", "path": "/api/admin/invoices", "permission": "invoices:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "starting_after": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "limit": 1, "starting_after": "example", "status": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/invoices", "body": null }, "effects": "Reads state through GET /api/admin/invoices without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/invoices", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.invoices.link.get", "title": "Get invoice link", "description": "Get the hosted link for an accessible invoice.", "method": "GET", "path": "/api/admin/invoices/{invoiceId}/link", "permission": "invoices:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "invoiceId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "invoiceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "invoiceId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/invoices/example/link", "body": null }, "effects": "Reads state through GET /api/admin/invoices/{invoiceId}/link without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/invoices/*/link", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.merchants.list", "title": "List admin merchants", "description": "List merchant accounts visible to the current workspace.", "method": "GET", "path": "/api/admin/merchants", "permission": "merchants:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/merchants", "body": null }, "effects": "Reads state through GET /api/admin/merchants without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/merchants", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "admin.merchants.get", "title": "Get admin merchant", "description": "Get a merchant account visible to the current workspace.", "method": "GET", "path": "/api/admin/merchants/{merchantId}", "permission": "merchants:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "merchantId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "merchantId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "merchantId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/admin/merchants/example", "body": null }, "effects": "Reads state through GET /api/admin/merchants/{merchantId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/admin/merchants/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "Delete Pay workspace", "description": "Delete a non-default empty Pay workspace.", "method": "DELETE", "path": "/api/pay/workspaces/{workspaceId}", "permission": "workspace:delete", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/pay/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/pay/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/pay/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.export", "title": "Export organization Pay data", "description": "Export the caller organization's billing, payment, settlement, usage, analytics, and attributed audit records across Pay's split stores.", "method": "GET", "path": "/api/organizations/{organizationId}/data", "permission": "privacy:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "organizationId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/example/data", "body": null }, "effects": "Reads state through GET /api/organizations/{organizationId}/data without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.erase", "title": "Erase organization Pay data", "description": "Erase organization-authored Pay content while retaining immutable financial and provider reconciliation records.", "method": "DELETE", "path": "/api/organizations/{organizationId}/data", "permission": "privacy:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "organizationId", "confirmation" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "organizationId": "example", "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/example/data", "body": null }, "effects": "May change state through DELETE /api/organizations/{organizationId}/data. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/*/data", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data_protection.canary", "title": "Check organization Pay protection", "description": "Check whether retained merchant, customer, transaction, refund, and provider payload fields are encrypted for an organization.", "method": "GET", "path": "/api/organizations/{organizationId}/data-protection", "permission": "privacy:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "organizationId": "example" }, "cli_example": [ "topolo actions --service topolo-pay --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/example/data-protection", "body": null }, "effects": "Reads state through GET /api/organizations/{organizationId}/data-protection without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/*/data-protection", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 80, "matched_actions": 58, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [ { "key": "POST /internal/platform/encryption/master-key/rewrap", "method": "POST", "path": "/internal/platform/encryption/master-key/rewrap", "source": "apps/api/src/index.ts", "target": "api" } ], "ignored_routes": 21, "configured_exclusions": 20, "configuration_findings": [], "notes": [] }, "runtime_contract_audit": { "status": "verified", "actions": 58, "contracts": 58, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/index.ts" ], "authorization_sources": [ "apps/api/src/index.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloPay/topolo.mobile-experience.json", "contract": { "version": "2026-06-29", "status": "approved", "mode": "native_capability", "appId": "app_topolo_pay", "localizationNamespace": "pay", "permissions": [ "transactions:read", "customers:read", "merchants:read" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/transactions", "auth": { "audience": "topolo-pay", "scopes": [ "transactions:read", "customers:read", "merchants:read" ] }, "routes": [ { "path": "/transactions", "apiPath": "/api/admin/transactions", "title": "Transactions", "titleKey": "pay.transactions.title", "template": "record.list", "dataSource": "pay.transactions.list", "detailRoute": "/transactions/:id" }, { "path": "/transactions/:id", "apiPath": "/api/admin/transaction/:id", "title": "Transactions", "titleKey": "pay.transactions.title", "template": "record.detail", "dataSource": "pay.transactions.detail" }, { "path": "/customers", "apiPath": "/api/admin/customers", "title": "Customers", "titleKey": "pay.shell.nav.customers", "template": "record.list", "dataSource": "pay.customers.list" }, { "path": "/merchants", "apiPath": "/api/merchants", "title": "Merchants", "titleKey": "pay.shell.nav.merchants", "template": "record.list", "dataSource": "pay.merchants.list", "detailRoute": "/merchants/:id" }, { "path": "/merchants/:id", "apiPath": "/api/admin/merchants/:id", "title": "Merchants", "titleKey": "pay.shell.nav.merchants", "template": "record.detail", "dataSource": "pay.merchants.detail" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "POST", "path": "/internal/platform/encryption/master-key/rewrap", "source_path": "apps/TopoloPay/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/p2p/settlements", "source_path": "apps/TopoloPay/apps/api/src/index.ts" }, { "method": "POST", "path": "/api/p2p/settlements/:batchId/complete", "source_path": "apps/TopoloPay/apps/api/src/index.ts" }, { "method": "GET", "path": "/api", "source_path": "apps/TopoloPay/apps/api/src/index.ts" }, { "method": "GET", "path": "/success", "source_path": "apps/TopoloPay/apps/api/src/index.ts" }, { "method": "GET", "path": "/cancel", "source_path": "apps/TopoloPay/apps/api/src/index.ts" }, { "method": "GET", "path": "/payment/:sessionId/status", "source_path": "apps/TopoloPay/apps/api/src/index.ts" }, { "method": "POST", "path": "/order/:paymentId/cancel", "source_path": "apps/TopoloPay/apps/api/src/index.ts" }, { "method": "GET", "path": "*", "source_path": "apps/TopoloPay/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/admin/transactions", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/api/admin/transaction/:id", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/api/admin/analytics", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/api/admin/merchants", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/api/admin/merchants/:id", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/api/admin/customers", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/api/admin/customers/:email/history", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/api/admin/invoices", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/api/admin/invoices/:id/link", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/api/admin/audit", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "POST", "path": "/api/admin/refund/:id", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "DELETE", "path": "/api/pay/workspaces/:workspaceId", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/api/organizations/:organizationId/data", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "DELETE", "path": "/api/organizations/:organizationId/data", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/api/organizations/:organizationId/data-protection", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/api/auth/me", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "ALL", "path": "/api/auth/*", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/api/admin/export", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/health", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/api/widget", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "/auth/callback", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" }, { "method": "GET", "path": "*", "source_path": "apps/TopoloPay/apps/api/src/routes/misc-routes.ts" } ], "ui_routes": [ { "path": "/dashboard", "source_path": "apps/TopoloPay/apps/web/src/App.tsx" }, { "path": "/transactions", "source_path": "apps/TopoloPay/apps/web/src/App.tsx" }, { "path": "/analytics", "source_path": "apps/TopoloPay/apps/web/src/App.tsx" }, { "path": "/customers", "source_path": "apps/TopoloPay/apps/web/src/App.tsx" }, { "path": "/merchants", "source_path": "apps/TopoloPay/apps/web/src/App.tsx" }, { "path": "/audit", "source_path": "apps/TopoloPay/apps/web/src/App.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloPay/apps/web/src/App.tsx" }, { "path": "/settings", "source_path": "apps/TopoloPay/apps/web/src/App.tsx" }, { "path": "/settings/:section", "source_path": "apps/TopoloPay/apps/web/src/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/pay", "internal/apps/pay" ], "present_paths": [ "applications/pay", "internal/apps/pay" ], "missing_paths": [], "human_reference": "/systems/topolo-pay", "machine_reference": "/machine/systems/topolo-pay.json", "action_examples": 58, "action_schemas": 58 }, "source_findings": [ { "type": "uncatalogued_routes", "source_path": "apps/TopoloPay/topolo.app.json", "detail": [ { "key": "POST /internal/platform/encryption/master-key/rewrap", "method": "POST", "path": "/internal/platform/encryption/master-key/rewrap", "source": "apps/api/src/index.ts", "target": "api" } ] } ] }, "topolo-platform": { "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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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" } ] } ] }, "topolo-quro": { "id": "topolo-quro", "name": "Topolo Quro", "slug": "topolo-quro", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloQuro" ], "source_revisions": [ { "source_path": "apps/TopoloQuro", "repository": "apps/TopoloQuro", "revision": "b92c14cb45d399a24de41ad2cb4d89a83abb1cbc", "ref": "origin/staging" } ], "source_counts": { "source_files": 86, "test_files": 54, "test_cases": 0, "migration_files": 12, "database_tables": 0, "manifests": 1, "deploy_targets": 3, "actions": 25, "mobile_contracts": 1, "notifications": 5, "package_manifests": 4, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloQuro/topolo.app.json", "service_slug": "topolo-quro", "name": "TopoloQuro", "app_id": "app_topolo_quro", "compatibility_date": "2026-04-10", "primary_target": null, "environments": [ "development", "production", "staging" ], "targets": [ { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "quro-ui", "subdomain": "quro", "healthcheck_path": null, "variable_names": [ "AUTH_API_URL", "INSIGHTS_SITE_KEY", "QURO_API_URL" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null } ] }, { "name": "api", "kind": "worker", "directory": "apps/api", "main": "index.js", "worker_name": "quro-api", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "APP_URL", "AUTH_BASE_URL", "BRAND_API_URL", "ENVIRONMENT", "QURO_PUBLIC_BASE_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "QURO_APP_DB", "target": null }, { "kind": "d1", "binding": "QURO_ANALYTICS_DB", "target": null }, { "kind": "kv", "binding": "QURO_REDIRECTS", "target": null }, { "kind": "kv", "binding": "QURO_REDIRECTS_A", "target": null }, { "kind": "kv", "binding": "QURO_REDIRECTS_B", "target": null }, { "kind": "kv", "binding": "QURO_SCANS_COUNT", "target": null }, { "kind": "kv", "binding": "QURO_SCANS_2025", "target": null }, { "kind": "kv", "binding": "QURO_SCANS_2026", "target": null } ] }, { "name": "redirect", "kind": "worker", "directory": "apps/redirect", "main": "index.js", "worker_name": "quro-redirect-system", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "AUTH_BASE_URL", "QURO_PUBLIC_BASE_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "QURO_APP_DB", "target": null }, { "kind": "d1", "binding": "QURO_ANALYTICS_DB", "target": null }, { "kind": "kv", "binding": "QURO_REDIRECTS", "target": null }, { "kind": "kv", "binding": "QURO_REDIRECTS_A", "target": null }, { "kind": "kv", "binding": "QURO_REDIRECTS_B", "target": null }, { "kind": "kv", "binding": "QURO_SCANS_COUNT", "target": null }, { "kind": "kv", "binding": "QURO_SCANS_2025", "target": null }, { "kind": "kv", "binding": "QURO_SCANS_2026", "target": null } ] } ], "notifications": [ "quro.code.published", "quro.destination.broken", "quro.export.ready", "quro.scan.threshold_reached", "quro.series.completed" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_quro", "events": [ { "type": "quro.code.published", "version": 1, "description": "An active Quro code and its redirect entry were durably published.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "code_id", "slug", "destination_url", "series_id", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "code_id": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "destination_url": { "type": "string", "minLength": 1 }, "series_id": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "QR code published: launch-2026", "body": "launch-2026 is active and ready to scan.", "object_id": "123", "code_id": "123", "slug": "launch-2026", "destination_url": "https://example.com/launch", "series_id": "42", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://quro.topolo.app/codes/launch-2026" } ], "dataClassification": "internal", "sensitiveFields": [ "destination_url" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^quro:code-published:" } }, { "type": "quro.destination.broken", "version": 1, "description": "A destination-health transition was persisted as a new open Quro incident.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "incident_id", "code_id", "slug", "destination_url", "reason", "http_status", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "incident_id": { "type": "string", "minLength": 1 }, "code_id": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "destination_url": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 }, "http_status": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "QR destination broken: launch-2026", "body": "launch-2026 can no longer reach its configured destination.", "object_id": "qurodestination_123", "incident_id": "qurodestination_123", "code_id": "123", "slug": "launch-2026", "destination_url": "https://example.com/launch", "reason": "HTTP_503", "http_status": 503, "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://quro.topolo.app/codes/launch-2026" } ], "dataClassification": "confidential", "sensitiveFields": [ "destination_url", "reason" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^quro:destination-broken:" } }, { "type": "quro.export.ready", "version": 1, "description": "A workspace-scoped Quro export artifact was persisted and is ready to download.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "export_id", "format", "record_count", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "export_id": { "type": "string", "minLength": 1 }, "format": { "type": "string", "const": "json" }, "record_count": { "type": "integer", "minimum": 0 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "QR code export ready", "body": "Your export containing 12 QR codes is ready.", "object_id": "quroexport_123", "export_id": "quroexport_123", "format": "json", "record_count": 12, "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://quro.topolo.app/exports/quroexport_123" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^quro:export-ready:" } }, { "type": "quro.scan.threshold_reached", "version": 1, "description": "A code's persisted scan count reached its configured maximum-usage threshold for the first time.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "threshold_id", "code_id", "slug", "scan_count", "threshold", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "threshold_id": { "type": "string", "minLength": 1 }, "code_id": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "scan_count": { "type": "integer", "minimum": 1 }, "threshold": { "type": "integer", "minimum": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "Scan threshold reached: launch-2026", "body": "launch-2026 reached its configured threshold of 1000 scans.", "object_id": "qurothreshold_123", "threshold_id": "qurothreshold_123", "code_id": "123", "slug": "launch-2026", "scan_count": 1000, "threshold": 1000, "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://quro.topolo.app/codes/launch-2026" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^quro:scan-threshold:" } }, { "type": "quro.series.completed", "version": 1, "description": "A workspace-owned Quro series was durably transitioned to completed.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "series_id", "series_name", "occurred_at", "cta_url" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "series_id": { "type": "string", "minLength": 1 }, "series_name": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": [ { "title": "QR series completed: Launch 2026", "body": "Launch 2026 has been marked completed.", "object_id": "42", "series_id": "42", "series_name": "Launch 2026", "occurred_at": "2026-07-20T00:00:00.000Z", "cta_url": "https://quro.topolo.app/series/42" } ], "dataClassification": "internal", "sensitiveFields": [], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^quro:series-completed:" } } ] }, "actions": [ { "name": "organizations.data.export", "title": "Export organization data", "description": "Export all Quro data owned by the authenticated organization across D1 and KV storage.", "method": "GET", "path": "/api/organizations/data/export", "permission": "privacy: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-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/data/export", "body": null }, "effects": "Reads state through GET /api/organizations/data/export without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/data/export", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.erase", "title": "Erase organization data", "description": "Permanently erase all Quro data owned by the authenticated organization while retaining backups under policy.", "method": "DELETE", "path": "/api/organizations/data/erase", "permission": "privacy:write", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/data/erase", "body": null }, "effects": "May change state through DELETE /api/organizations/data/erase. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/data/erase", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "codes: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-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "workspaces.delete", "title": "Archive workspace", "description": "Archive an empty Quro workspace via the platform, then drop Quro's local mirror row.", "method": "DELETE", "path": "/api/quro/workspaces/{workspaceId}", "permission": "workspace:delete", "authorizationMode": "static", "readOnly": false, "inputSchema": { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "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-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/quro/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/quro/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/quro/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "qurocodes.list", "title": "List QURO codes", "description": "List QURO codes.", "method": "GET", "path": "/qurocodes", "permission": "codes:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "tier": { "type": "string", "enum": [ "all", "basic", "standard", "premium" ] }, "search": { "type": "string", "minLength": 1 }, "statusId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "categoryId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "seriesId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List QURO codes.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "page": 1, "perPage": 1, "limit": 1 }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/qurocodes", "body": null }, "effects": "Reads state through GET /qurocodes without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /qurocodes", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "qurocodes.create", "title": "Create QURO codes", "description": "Create QURO codes.", "method": "POST", "path": "/qurocodes", "permission": "codes:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "tier": { "type": "string", "enum": [ "basic", "standard", "premium" ] }, "status_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "category_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "series_id": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1 }, "max_usage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "valid_from": { "type": "string", "minLength": 1 }, "valid_to": { "type": "string", "minLength": 1 }, "design": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "plain" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "custom" }, "foreground": { "type": "string", "pattern": "^#[0-9a-f]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-f]{6}$" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "brand" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false } ] } }, "required": [ "url" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create QURO codes.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "url": "https://example.com" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/qurocodes", "body": { "url": "https://example.com" } }, "effects": "May change state through POST /qurocodes. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /qurocodes", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "qurocodes.get", "title": "Get QURO codes", "description": "Get one QURO codes record.", "method": "GET", "path": "/qurocodes/{id_or_slug}", "permission": "codes:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id_or_slug": { "type": "string", "minLength": 1 } }, "required": [ "id_or_slug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get QURO codes.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "id_or_slug": "example" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/qurocodes/example", "body": null }, "effects": "Reads state through GET /qurocodes/{id_or_slug} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /qurocodes/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "qurocodes.update", "title": "Update QURO codes", "description": "Update one QURO codes record.", "method": "PUT", "path": "/qurocodes/{id_or_slug}", "permission": "codes:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id_or_slug": { "type": "string", "minLength": 1 }, "url": { "type": "string", "minLength": 1 }, "status_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "category_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "series_id": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "name": { "type": "string" }, "max_usage": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "valid_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "valid_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "design": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "plain" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "custom" }, "foreground": { "type": "string", "pattern": "^#[0-9a-f]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-f]{6}$" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "brand" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false } ] } }, "required": [ "id_or_slug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update QURO codes.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "id_or_slug": "example" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/qurocodes/example", "body": { "id_or_slug": "example" } }, "effects": "May change state through PUT /qurocodes/{id_or_slug}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /qurocodes/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "qurocodes.delete", "title": "Delete QURO codes", "description": "Delete one QURO codes record.", "method": "DELETE", "path": "/qurocodes/{id_or_slug}", "permission": "codes:write", "authorizationMode": "static", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id_or_slug": { "type": "string", "minLength": 1 } }, "required": [ "id_or_slug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Delete QURO codes.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "documentation": { "example_input": { "id_or_slug": "example" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/qurocodes/example", "body": null }, "effects": "May change state through DELETE /qurocodes/{id_or_slug}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /qurocodes/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "analytics.get", "title": "Get analytics", "description": "Get Quro analytics.", "method": "GET", "path": "/analytics", "permission": "analytics:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "quro_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "slug": { "type": "string", "minLength": 1 }, "period": { "type": "string", "enum": [ "day", "week", "month", "year" ] } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get analytics.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "quro_id": 1, "slug": "example", "period": "day" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/analytics", "body": null }, "effects": "Reads state through GET /analytics without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /analytics", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "analytics.assets.list", "title": "List analytics assets", "description": "List Quro OpenClaw analytics assets.", "method": "GET", "path": "/openclaw/quro/assets", "permission": "analytics:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100 }, "search": { "type": "string", "minLength": 1 }, "tier": { "type": "string", "enum": [ "all", "basic", "standard", "premium" ] }, "seriesId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "refresh_health": { "type": "string", "enum": [ "true", "false" ] }, "inactivity_days": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "window_days": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List analytics assets.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "page": 1, "perPage": 1, "search": "example" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/openclaw/quro/assets", "body": null }, "effects": "Reads state through GET /openclaw/quro/assets without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /openclaw/quro/assets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "analytics.events.list", "title": "List analytics events", "description": "List Quro OpenClaw analytics events.", "method": "GET", "path": "/openclaw/quro/events", "permission": "analytics:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "quro_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "event_type": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List analytics events.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "from": "example", "to": "example", "slug": "example" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/openclaw/quro/events", "body": null }, "effects": "Reads state through GET /openclaw/quro/events without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /openclaw/quro/events", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "analytics.rollups.list", "title": "List analytics rollups", "description": "List Quro OpenClaw analytics rollups.", "method": "GET", "path": "/openclaw/quro/rollups", "permission": "analytics:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "quro_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List analytics rollups.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "from": "example", "to": "example", "slug": "example" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/openclaw/quro/rollups", "body": null }, "effects": "Reads state through GET /openclaw/quro/rollups without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /openclaw/quro/rollups", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "analytics.summary.get", "title": "Get analytics summary", "description": "Get Quro OpenClaw analytics summary.", "method": "GET", "path": "/openclaw/quro/summary", "permission": "analytics:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "inactivity_days": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "window_days": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get analytics summary.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "inactivity_days": 1, "window_days": 1, "limit": 1 }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/openclaw/quro/summary", "body": null }, "effects": "Reads state through GET /openclaw/quro/summary without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /openclaw/quro/summary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "metadata.get", "title": "Get metadata", "description": "Get Quro metadata by type.", "method": "GET", "path": "/metadata/{type}", "permission": "settings:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string", "enum": [ "categories", "statuses", "tiers" ] } }, "required": [ "type" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get metadata.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "type": "categories" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/metadata/categories", "body": null }, "effects": "Reads state through GET /metadata/{type} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /metadata/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "series.list", "title": "List series", "description": "List Quro series.", "method": "GET", "path": "/series", "permission": "series:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100 }, "includeArchived": { "type": "string", "enum": [ "true", "false" ] }, "status": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List series.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "page": 1, "perPage": 1, "includeArchived": "true" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/series", "body": null }, "effects": "Reads state through GET /series without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /series", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "series.create", "title": "Create series", "description": "Create a Quro series.", "method": "POST", "path": "/series", "permission": "series:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "templateId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create series.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "name": "example", "description": "example", "status": "active" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/series", "body": { "name": "example", "description": "example", "status": "active" } }, "effects": "May change state through POST /series. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /series", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "series.templates.list", "title": "List series templates", "description": "List Quro series templates.", "method": "GET", "path": "/series/templates", "permission": "series:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List series templates.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "search": "example", "category": "example" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/series/templates", "body": null }, "effects": "Reads state through GET /series/templates without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /series/templates", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "series.dashboard.get", "title": "Get series dashboard", "description": "Get one Quro series dashboard.", "method": "GET", "path": "/series/{id}/dashboard", "permission": "series:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get series dashboard.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/series/00000000-0000-4000-8000-000000000000/dashboard", "body": null }, "effects": "Reads state through GET /series/{id}/dashboard without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /series/*/dashboard", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "series.dashboard.update", "title": "Update series dashboard", "description": "Update one Quro series dashboard.", "method": "PUT", "path": "/series/{id}/dashboard", "permission": "series:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "dashboard": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "resetToDefault": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update series dashboard.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/series/00000000-0000-4000-8000-000000000000/dashboard", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /series/{id}/dashboard. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /series/*/dashboard", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "series.generate", "title": "Generate series", "description": "Generate Quro codes for a series.", "method": "POST", "path": "/series/{id}/generate", "permission": "series:write", "authorizationMode": "static", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "count": { "type": "integer", "minimum": 1, "maximum": 1000 }, "tier": { "type": "string", "enum": [ "basic", "standard", "premium" ] }, "namePattern": { "type": "string", "minLength": 1 }, "urlPattern": { "type": "string", "minLength": 1 }, "categoryId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "statusId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "startNumber": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "design": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "plain" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "custom" }, "foreground": { "type": "string", "pattern": "^#[0-9a-f]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-f]{6}$" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "brand" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false } ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Generate series.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/series/00000000-0000-4000-8000-000000000000/generate", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /series/{id}/generate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /series/*/generate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "series.generation_templates.list", "title": "List generation templates", "description": "List generation templates for a Quro series.", "method": "GET", "path": "/series/{id}/generation-templates", "permission": "series:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List generation templates.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/series/00000000-0000-4000-8000-000000000000/generation-templates", "body": null }, "effects": "Reads state through GET /series/{id}/generation-templates without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /series/*/generation-templates", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "series.complete", "title": "Complete series", "description": "Mark a Quro series completed.", "method": "POST", "path": "/series/{id}/complete", "permission": "series:write", "authorizationMode": "static", "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "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", "additionalProperties": true }, "target": "api", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/series/00000000-0000-4000-8000-000000000000/complete", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /series/{id}/complete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /series/*/complete", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "exports.create", "title": "Create Quro export", "description": "Create a durable JSON export of the active workspace's Quro codes.", "method": "POST", "path": "/exports", "permission": "codes:read", "authorizationMode": "static", "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/exports", "body": {} }, "effects": "May change state through POST /exports. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /exports", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "exports.download", "title": "Download Quro export", "description": "Download a ready Quro export artifact.", "method": "GET", "path": "/exports/{id}", "permission": "codes:read", "authorizationMode": "static", "readOnly": true, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "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", "additionalProperties": true }, "target": "api", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-quro --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/exports/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /exports/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /exports/*", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 31, "matched_actions": 25, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 6, "configured_exclusions": 4, "configuration_findings": [], "notes": [ "no routes extracted from redirect" ] }, "runtime_contract_audit": { "status": "verified", "actions": 25, "contracts": 25, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/index.js" ], "authorization_sources": [ "apps/api/index.js" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloQuro/topolo.mobile-experience.json", "contract": { "version": "2026-07-03", "status": "approved", "mode": "native_capability", "appId": "app_topolo_quro", "localizationNamespace": "quro", "permissions": [ "codes:read", "codes:write", "series:read", "series:write", "analytics:read" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/dashboard", "auth": { "audience": "topolo-quro", "scopes": [ "codes:read", "codes:write", "series:read", "series:write", "analytics:read" ], "orgContext": "required" }, "routes": [ { "path": "/dashboard", "apiPath": "/qurocodes", "title": "QR codes", "titleKey": "quro.mobile.routes.codes.title", "template": "record.list", "dataSource": "quro.codes.list", "detailRoute": "/codes/:slug", "actions": [ { "id": "quro.codes.create", "title": "Create QR code", "titleKey": "quro.mobile.actions.codesCreate.title", "type": "record.create", "permission": "codes:write", "method": "POST", "path": "/qurocodes", "fields": [ { "key": "url", "label": "Destination URL", "type": "text", "required": true }, { "key": "name", "label": "Name", "type": "text" }, { "key": "tier", "label": "Tier", "type": "text" }, { "key": "category", "label": "Category", "type": "text" }, { "key": "series", "label": "Series", "type": "text" }, { "key": "valid_from", "label": "Valid from", "type": "date" }, { "key": "valid_to", "label": "Valid to", "type": "date" } ] } ] }, { "path": "/codes/:slug", "apiPath": "/qurocodes/:slug", "title": "QR code", "titleKey": "quro.mobile.routes.codeDetail.title", "template": "record.detail", "dataSource": "quro.codes.detail", "actions": [ { "id": "quro.codes.update", "title": "Update QR code", "titleKey": "quro.mobile.actions.codeUpdate.title", "type": "record.update", "permission": "codes:write", "method": "PUT", "path": "/qurocodes/:slug", "fields": [ { "key": "url", "label": "Destination URL", "type": "text" }, { "key": "name", "label": "Name", "type": "text" }, { "key": "category", "label": "Category", "type": "text" } ] }, { "id": "quro.codes.delete", "title": "Delete QR code", "titleKey": "quro.mobile.actions.codeDelete.title", "type": "record.delete", "permission": "codes:write", "method": "DELETE", "path": "/qurocodes/:slug" } ] }, { "path": "/series", "apiPath": "/series", "title": "Series", "titleKey": "quro.mobile.routes.series.title", "template": "record.list", "dataSource": "quro.series.list", "detailRoute": "/series/:id/dashboard", "actions": [ { "id": "quro.series.create", "title": "Create series", "titleKey": "quro.mobile.actions.seriesCreate.title", "type": "record.create", "permission": "series:write", "method": "POST", "path": "/series", "fields": [ { "key": "name", "label": "Name", "type": "text", "required": true }, { "key": "description", "label": "Description", "type": "textarea" } ] } ] }, { "path": "/series/:id/dashboard", "apiPath": "/series/:id/dashboard", "title": "Series dashboard", "titleKey": "quro.mobile.routes.seriesDashboard.title", "template": "record.detail", "dataSource": "quro.series.detail" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "ALL", "path": "*", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "OPTIONS", "path": "*", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/health", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/api/widget", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/api/organizations/data/export", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "DELETE", "path": "/api/organizations/data/erase", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "DELETE", "path": "/api/quro/workspaces/:workspaceId", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/analytics", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/openclaw/quro/assets", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/openclaw/quro/events", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/openclaw/quro/rollups", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/openclaw/quro/summary", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/metadata/:type", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/series", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/series/templates", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "POST", "path": "/series", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/series/:id/dashboard", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "PUT", "path": "/series/:id/dashboard", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "POST", "path": "/series/:id/generate", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/series/:id/generation-templates", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/qr/:slug", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/qr/test/:slug", "source_path": "apps/TopoloQuro/apps/api/index.js" }, { "method": "GET", "path": "/qr/design-context", "source_path": "apps/TopoloQuro/apps/api/src/quro-code-routes.js" }, { "method": "POST", "path": "/qr/preview.svg", "source_path": "apps/TopoloQuro/apps/api/src/quro-code-routes.js" }, { "method": "GET", "path": "/qurocodes", "source_path": "apps/TopoloQuro/apps/api/src/quro-code-routes.js" }, { "method": "POST", "path": "/qurocodes", "source_path": "apps/TopoloQuro/apps/api/src/quro-code-routes.js" }, { "method": "GET", "path": "/qurocodes/:id_or_slug", "source_path": "apps/TopoloQuro/apps/api/src/quro-code-routes.js" }, { "method": "PUT", "path": "/qurocodes/:id_or_slug", "source_path": "apps/TopoloQuro/apps/api/src/quro-code-routes.js" }, { "method": "DELETE", "path": "/qurocodes/:id_or_slug", "source_path": "apps/TopoloQuro/apps/api/src/quro-code-routes.js" }, { "method": "POST", "path": "/series/:id/complete", "source_path": "apps/TopoloQuro/apps/api/src/quro-workflow-routes.js" }, { "method": "POST", "path": "/exports", "source_path": "apps/TopoloQuro/apps/api/src/quro-workflow-routes.js" }, { "method": "GET", "path": "/exports/:id", "source_path": "apps/TopoloQuro/apps/api/src/quro-workflow-routes.js" }, { "method": "LITERAL", "path": "/health", "source_path": "apps/TopoloQuro/apps/redirect/index.js" } ], "ui_routes": [ { "path": "/dashboard", "source_path": "apps/TopoloQuro/apps/web/src/App.tsx" }, { "path": "/create", "source_path": "apps/TopoloQuro/apps/web/src/App.tsx" }, { "path": "/codes/:slug", "source_path": "apps/TopoloQuro/apps/web/src/App.tsx" }, { "path": "/series", "source_path": "apps/TopoloQuro/apps/web/src/App.tsx" }, { "path": "/series/:id/dashboard", "source_path": "apps/TopoloQuro/apps/web/src/App.tsx" }, { "path": "/settings", "source_path": "apps/TopoloQuro/apps/web/src/App.tsx" }, { "path": "/settings/:section", "source_path": "apps/TopoloQuro/apps/web/src/App.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloQuro/apps/web/src/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/quro", "internal/apps/quro" ], "present_paths": [ "applications/quro", "internal/apps/quro" ], "missing_paths": [], "human_reference": "/systems/topolo-quro", "machine_reference": "/machine/systems/topolo-quro.json", "action_examples": 25, "action_schemas": 25 }, "source_findings": [] }, "topolo-roadmapper": { "id": "topolo-roadmapper", "name": "Topolo Roadmapper", "slug": "topolo-roadmapper", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloRoadmapper" ], "source_revisions": [ { "source_path": "apps/TopoloRoadmapper", "repository": "apps/TopoloRoadmapper", "revision": "4d949b9e65b36e73fd832edcf0a142205a1db5bd", "ref": "origin/staging" } ], "source_counts": { "source_files": 222, "test_files": 140, "test_cases": 0, "migration_files": 10, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 74, "mobile_contracts": 1, "notifications": 8, "package_manifests": 5, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloRoadmapper/topolo.app.json", "service_slug": "topolo-roadmapper", "name": "topolo-roadmapper", "app_id": "app_topolo_roadmapper", "compatibility_date": "2026-04-10", "primary_target": null, "environments": [ "development", "production", "staging" ], "targets": [ { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-roadmapper", "subdomain": "roadmapper", "healthcheck_path": null, "variable_names": [ "AUTH_API_URL", "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null } ] }, { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/index.ts", "worker_name": "topolo-roadmapper-api", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "ENVIRONMENT", "FRONTEND_URL", "TOPOLO_AUTH_API_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "ROADMAP_CORE_DB", "target": null }, { "kind": "d1", "binding": "ROADMAP_COLLAB_DB", "target": null }, { "kind": "d1", "binding": "ROADMAP_PLANNING_DB", "target": null }, { "kind": "d1", "binding": "ROADMAP_EXPORT_DB", "target": null }, { "kind": "r2", "binding": "ATTACHMENTS_BUCKET", "target": null } ] } ], "notifications": [ "roadmapper.comment.mention", "roadmapper.dependency.blocked", "roadmapper.guest_share.invited", "roadmapper.item.assigned", "roadmapper.item.due", "roadmapper.presentation.ready", "roadmapper.project.created", "roadmapper.roadmap.created" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_roadmapper", "events": [ { "type": "roadmapper.comment.mention", "version": 1, "description": "A Roadmapper comment durably mentioned an organization member.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "comment_id", "item_id", "item_name", "comment_excerpt", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "comment_id": { "type": "string", "minLength": 1 }, "item_id": { "type": "string", "minLength": 1 }, "item_name": { "type": "string", "minLength": 1 }, "comment_excerpt": { "type": "string", "maxLength": 240 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "title": "Ada mentioned you in a comment", "body": "Ada mentioned you on Launch API.", "comment_id": "comment_123", "item_id": "item_123", "item_name": "Launch API", "comment_excerpt": "Please review this dependency.", "object_id": "comment_123", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^roadmapper:comment-mention:" }, "sensitiveFields": [] }, { "type": "roadmapper.dependency.blocked", "version": 1, "description": "A persisted blocks or requires dependency blocked an assigned Roadmapper item.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "dependency_id", "dependency_type", "blocked_item_id", "blocked_item_name", "blocking_item_id", "blocking_item_name", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "dependency_id": { "type": "string", "minLength": 1 }, "dependency_type": { "enum": [ "blocks", "requires" ] }, "blocked_item_id": { "type": "string", "minLength": 1 }, "blocked_item_name": { "type": "string", "minLength": 1 }, "blocking_item_id": { "type": "string", "minLength": 1 }, "blocking_item_name": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "examples": [ { "title": "Roadmap item blocked", "body": "Launch API is blocked by Authentication rollout.", "dependency_id": "dependency_123", "dependency_type": "blocks", "blocked_item_id": "item_123", "blocked_item_name": "Launch API", "blocking_item_id": "item_456", "blocking_item_name": "Authentication rollout", "object_id": "item_123", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^roadmapper:dependency-blocked:" }, "sensitiveFields": [] }, { "type": "roadmapper.guest_share.invited", "version": 1, "description": "Roadmapper recorded the durable guest share invited transition.", "status": "published", "payloadSchema": { "type": "object", "additionalProperties": false, "required": [ "recipient_email", "resource_label", "resource_name", "share_url", "access_mode", "allow_item_navigation", "occurred_at" ], "properties": { "recipient_email": { "type": "string", "format": "email" }, "resource_label": { "type": "string", "minLength": 1 }, "resource_name": { "type": "string", "minLength": 1 }, "share_url": { "type": "string", "format": "uri" }, "access_mode": { "enum": [ "view", "edit" ] }, "allow_item_navigation": { "type": "boolean" }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" } } }, "examples": [ { "recipient_email": "guest@example.com", "resource_label": "Roadmap", "resource_name": "Product launch", "share_url": "https://roadmapper.topolo.app/roadmaps/guest/share_123", "access_mode": "view", "allow_item_navigation": true, "occurred_at": "2026-07-17T12:00:00.000Z" } ], "dataClassification": "confidential", "sensitiveFields": [ "recipient_email", "share_url" ], "recipients": { "modes": [ "external" ], "externalAddress": "required" }, "idempotency": { "required": true, "pattern": "^roadmapper:guest-share-invited:" } }, { "type": "roadmapper.item.assigned", "version": 1, "description": "A Roadmapper item durably acquired a new member assignee.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "item_id", "item_name", "assignee_user_id", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "item_id": { "type": "string", "minLength": 1 }, "item_name": { "type": "string", "minLength": 1 }, "assignee_user_id": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" }, "actor_id": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "title": "Roadmap item assigned to you", "body": "Ada assigned Launch API to you.", "item_id": "item_123", "item_name": "Launch API", "assignee_user_id": "usr_123", "object_id": "item_123", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^roadmapper:item-assigned:" }, "sensitiveFields": [] }, { "type": "roadmapper.item.due", "version": 1, "description": "A persisted assigned Roadmapper item reached its due date and had not completed.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "item_id", "item_name", "due_date", "assignee_user_id", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "item_id": { "type": "string", "minLength": 1 }, "item_name": { "type": "string", "minLength": 1 }, "due_date": { "type": "string", "format": "date" }, "assignee_user_id": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "examples": [ { "title": "Roadmap item is due", "body": "Launch API is due on 2026-07-20.", "item_id": "item_123", "item_name": "Launch API", "due_date": "2026-07-20", "assignee_user_id": "usr_123", "object_id": "item_123", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^roadmapper:item-due:" }, "sensitiveFields": [] }, { "type": "roadmapper.presentation.ready", "version": 1, "description": "A Roadmapper presentation deck was durably generated in ready state.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "presentation_id", "presentation_title", "project_id", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "presentation_id": { "type": "string", "minLength": 1 }, "presentation_title": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "cta_url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "examples": [ { "title": "Presentation ready", "body": "Launch review is ready to review.", "presentation_id": "presentation_123", "presentation_title": "Launch review", "project_id": "project_123", "object_id": "presentation_123", "occurred_at": "2026-07-20T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^roadmapper:presentation-ready:" }, "sensitiveFields": [] }, { "type": "roadmapper.project.created", "version": 1, "description": "A roadmap project was created.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "thread_key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "A roadmap project was created.", "body": "Open the owning app to review this event.", "object_id": "object_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^roadmapper:project-created:" }, "sensitiveFields": [] }, { "type": "roadmapper.roadmap.created", "version": 1, "description": "A roadmap was created.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "thread_key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "A roadmap was created.", "body": "Open the owning app to review this event.", "object_id": "object_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^roadmapper:roadmap-created:" }, "sensitiveFields": [] } ] }, "actions": [ { "name": "organizations.data.export", "title": "Export organization data", "description": "Export all Roadmapper data owned by the authenticated organization across four D1 stores and linked attachment metadata.", "method": "GET", "path": "/api/organizations/data/export", "permission": "privacy:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/data/export", "body": null }, "effects": "Reads state through GET /api/organizations/data/export without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/data/export", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.erase", "title": "Erase organization data", "description": "Permanently erase all Roadmapper data owned by the authenticated organization while retaining backups under policy.", "method": "DELETE", "path": "/api/organizations/data/erase", "permission": "privacy:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/data/erase", "body": null }, "effects": "May change state through DELETE /api/organizations/data/erase. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/data/erase", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.list", "title": "Projects List", "description": "Execute Projects List in Topolo Roadmapper.", "method": "GET", "path": "/api/projects", "permission": "projects:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/projects", "body": null }, "effects": "Reads state through GET /api/projects without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/projects", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.create", "title": "Projects Create", "description": "Call POST /projects.", "method": "POST", "path": "/api/projects", "permission": "projects:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "status": { "type": "string", "enum": [ "active", "on_hold", "completed", "cancelled", "archived" ] } }, "required": [ "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "name": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects", "body": { "name": "example" } }, "effects": "May change state through POST /api/projects. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/projects", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.update", "title": "Projects Update", "description": "Call PUT /projects/{id}.", "method": "PUT", "path": "/api/projects/{id}", "permission": "projects:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "status": { "type": "string", "enum": [ "active", "on_hold", "completed", "cancelled", "archived" ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/projects/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/projects/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/projects/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.delete", "title": "Projects Delete", "description": "Call DELETE /projects/{id}.", "method": "DELETE", "path": "/api/projects/{id}", "permission": "projects:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/projects/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/projects/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/projects/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.archive", "title": "Projects Archive", "description": "Call POST /projects/{id}/archive.", "method": "POST", "path": "/api/projects/{id}/archive", "permission": "projects:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "archive": { "type": "boolean" } }, "required": [ "id", "archive" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Archive.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "archive": true }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects/00000000-0000-4000-8000-000000000000/archive", "body": { "id": "00000000-0000-4000-8000-000000000000", "archive": true } }, "effects": "May change state through POST /api/projects/{id}/archive. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/projects/*/archive", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.guest_shares.create", "title": "Projects Guest Shares Create", "description": "Execute Projects Guest Shares Create in Topolo Roadmapper.", "method": "POST", "path": "/api/projects/{id}/share-guest", "permission": "projects:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "expiresInHours": { "anyOf": [ { "type": "number", "minimum": 1, "maximum": 720 }, { "type": "null" } ] }, "accessMode": { "type": "string", "enum": [ "view", "edit" ] }, "allowItemNavigation": { "type": "boolean" }, "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects/00000000-0000-4000-8000-000000000000/share-guest", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/projects/{id}/share-guest. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/projects/*/share-guest", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.guest_shares.list", "title": "Projects Guest Shares List", "description": "Execute Projects Guest Shares List in Topolo Roadmapper.", "method": "GET", "path": "/api/projects/{id}/share-guest", "permission": "projects:read", "readOnly": true, "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", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/projects/00000000-0000-4000-8000-000000000000/share-guest", "body": null }, "effects": "Reads state through GET /api/projects/{id}/share-guest without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/projects/*/share-guest", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.guest_shares.revoke", "title": "Projects Guest Shares Revoke", "description": "Execute Projects Guest Shares Revoke in Topolo Roadmapper.", "method": "DELETE", "path": "/api/projects/{id}/share-guest/{token}", "permission": "projects:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 } }, "required": [ "id", "token" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "token": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/projects/00000000-0000-4000-8000-000000000000/share-guest/example", "body": null }, "effects": "May change state through DELETE /api/projects/{id}/share-guest/{token}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/projects/*/share-guest/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.guest_shares.invite", "title": "Projects Guest Shares Invite", "description": "Execute Projects Guest Shares Invite in Topolo Roadmapper.", "method": "POST", "path": "/api/projects/{id}/share-guest/{token}/invite-email", "permission": "projects:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "recipientEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "id", "token", "recipientEmail" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "token": "example", "recipientEmail": "user@example.com" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects/00000000-0000-4000-8000-000000000000/share-guest/example/invite-email", "body": { "id": "00000000-0000-4000-8000-000000000000", "token": "example", "recipientEmail": "user@example.com" } }, "effects": "May change state through POST /api/projects/{id}/share-guest/{token}/invite-email. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/projects/*/share-guest/*/invite-email", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.presentations.generate", "title": "Projects Presentations Generate", "description": "Call POST /projects/{id}/presentations/generate.", "method": "POST", "path": "/api/projects/{id}/presentations/generate", "permission": "reports:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "template": { "type": "string", "enum": [ "executive_status_update", "steering_committee_review", "program_increment_review", "customer_safe_roadmap_update", "delivery_risk_review" ] }, "scenarioId": { "type": "string" }, "liveLinked": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Presentations Generate.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects/00000000-0000-4000-8000-000000000000/presentations/generate", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/projects/{id}/presentations/generate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/projects/*/presentations/generate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.planning_sessions.create", "title": "Projects Planning Sessions Create", "description": "Call POST /projects/{id}/planning/sessions.", "method": "POST", "path": "/api/projects/{id}/planning/sessions", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "scopeType": { "type": "string", "enum": [ "project", "roadmap", "item" ] }, "scopeRecordId": { "type": "string", "minLength": 1, "maxLength": 128 }, "impactMode": { "type": "string", "enum": [ "project_wide", "selected_only", "selected_with_descendants" ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Planning Sessions Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects/00000000-0000-4000-8000-000000000000/planning/sessions", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/projects/{id}/planning/sessions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/projects/*/planning/sessions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.ai_draft.create", "title": "Projects Ai Draft Create", "description": "Call POST /projects/ai/draft.", "method": "POST", "path": "/api/projects/ai/draft", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messages": { "minItems": 1, "maxItems": 40, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "role", "content" ], "additionalProperties": false } }, "currentDraft": { "anyOf": [ { "type": "object", "properties": { "project": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "name" ], "additionalProperties": false }, "roadmaps": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "blocked" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "assignee": { "type": "string", "maxLength": 255 }, "children": { "type": "array", "items": {} } }, "required": [ "name" ], "additionalProperties": false } } }, "required": [ "name", "items" ], "additionalProperties": false } } }, "required": [ "project", "roadmaps" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "messages" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Ai Draft Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "messages": [ { "role": "user", "content": "example" } ] }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects/ai/draft", "body": { "messages": [ { "role": "user", "content": "example" } ] } }, "effects": "May change state through POST /api/projects/ai/draft. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/projects/ai/draft", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.ai_apply", "title": "Projects Ai Apply", "description": "Call POST /projects/ai/apply.", "method": "POST", "path": "/api/projects/ai/apply", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "draft": { "type": "object", "properties": { "project": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "name" ], "additionalProperties": false }, "roadmaps": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "blocked" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "assignee": { "type": "string", "maxLength": 255 }, "children": { "type": "array", "items": {} } }, "required": [ "name" ], "additionalProperties": false } } }, "required": [ "name", "items" ], "additionalProperties": false } } }, "required": [ "project", "roadmaps" ], "additionalProperties": false } }, "required": [ "draft" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Ai Apply.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "draft": { "project": { "name": "example" }, "roadmaps": [ { "name": "example", "items": [ { "name": "example" } ] } ] } }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects/ai/apply", "body": { "draft": { "project": { "name": "example" }, "roadmaps": [ { "name": "example", "items": [ { "name": "example" } ] } ] } } }, "effects": "May change state through POST /api/projects/ai/apply. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/projects/ai/apply", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.ai_sessions.create", "title": "Projects Ai Sessions Create", "description": "Call POST /projects/ai/sessions.", "method": "POST", "path": "/api/projects/ai/sessions", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Ai Sessions Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects/ai/sessions", "body": {} }, "effects": "May change state through POST /api/projects/ai/sessions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/projects/ai/sessions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.ai_sessions.update", "title": "Projects Ai Sessions Update", "description": "Call PATCH /projects/ai/sessions/{id}.", "method": "PATCH", "path": "/api/projects/ai/sessions/{id}", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "draft": { "anyOf": [ { "type": "object", "properties": { "project": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "name" ], "additionalProperties": false }, "roadmaps": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "blocked" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "assignee": { "type": "string", "maxLength": 255 }, "children": { "type": "array", "items": {} } }, "required": [ "name" ], "additionalProperties": false } } }, "required": [ "name", "items" ], "additionalProperties": false } } }, "required": [ "project", "roadmaps" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "draft" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Ai Sessions Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "draft": { "project": { "name": "example" }, "roadmaps": [ { "name": "example", "items": [] } ] } }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/projects/ai/sessions/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000", "draft": { "project": { "name": "example" }, "roadmaps": [ { "name": "example", "items": [] } ] } } }, "effects": "May change state through PATCH /api/projects/ai/sessions/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/projects/ai/sessions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.ai_sessions.delete", "title": "Projects Ai Sessions Delete", "description": "Call DELETE /projects/ai/sessions/{id}.", "method": "DELETE", "path": "/api/projects/ai/sessions/{id}", "permission": "roadmaps:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Ai Sessions Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/projects/ai/sessions/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/projects/ai/sessions/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/projects/ai/sessions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.ai_sessions.turns.create", "title": "Projects Ai Sessions Turns Create", "description": "Call POST /projects/ai/sessions/{id}/turns.", "method": "POST", "path": "/api/projects/ai/sessions/{id}/turns", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "id", "message" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Ai Sessions Turns Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "message": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects/ai/sessions/00000000-0000-4000-8000-000000000000/turns", "body": { "id": "00000000-0000-4000-8000-000000000000", "message": "example" } }, "effects": "May change state through POST /api/projects/ai/sessions/{id}/turns. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/projects/ai/sessions/*/turns", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.ai_sessions.apply", "title": "Projects Ai Sessions Apply", "description": "Call POST /projects/ai/sessions/{id}/apply.", "method": "POST", "path": "/api/projects/ai/sessions/{id}/apply", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Ai Sessions Apply.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/projects/ai/sessions/00000000-0000-4000-8000-000000000000/apply", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/projects/ai/sessions/{id}/apply. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/projects/ai/sessions/*/apply", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "items.create", "title": "Items Create", "description": "Call POST /items.", "method": "POST", "path": "/api/items", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "roadmapId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "blocked" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "assignee": { "type": "string", "maxLength": 255 }, "assigneeUserId": { "type": "string", "minLength": 1, "maxLength": 255 }, "parentItemId": { "type": "string" } }, "required": [ "roadmapId", "name", "status", "priority" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Items Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "roadmapId": "example", "name": "example", "status": "planned", "priority": "low" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/items", "body": { "roadmapId": "example", "name": "example", "status": "planned", "priority": "low" } }, "effects": "May change state through POST /api/items. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/items", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "items.update", "title": "Items Update", "description": "Call PATCH /items/{id}.", "method": "PATCH", "path": "/api/items/{id}", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "blocked" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "assignee": { "type": "string", "maxLength": 255 }, "assigneeUserId": { "type": "string", "minLength": 1, "maxLength": 255 }, "parentItemId": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Items Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/items/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PATCH /api/items/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/items/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "items.delete", "title": "Items Delete", "description": "Call DELETE /items/{id}.", "method": "DELETE", "path": "/api/items/{id}", "permission": "roadmaps:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Items Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/items/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/items/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/items/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "items.presentations.generate", "title": "Items Presentations Generate", "description": "Call POST /items/{id}/presentations/generate.", "method": "POST", "path": "/api/items/{id}/presentations/generate", "permission": "reports:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "template": { "type": "string", "enum": [ "executive_status_update", "steering_committee_review", "program_increment_review", "customer_safe_roadmap_update", "delivery_risk_review" ] }, "scenarioId": { "type": "string" }, "liveLinked": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Items Presentations Generate.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/items/00000000-0000-4000-8000-000000000000/presentations/generate", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/items/{id}/presentations/generate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/items/*/presentations/generate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "items.guest_shares.create", "title": "Items Guest Shares Create", "description": "Execute Items Guest Shares Create in Topolo Roadmapper.", "method": "POST", "path": "/api/items/{id}/share-guest", "permission": "roadmaps:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "expiresInHours": { "anyOf": [ { "type": "number", "minimum": 1, "maximum": 720 }, { "type": "null" } ] }, "accessMode": { "type": "string", "enum": [ "view", "edit" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/items/00000000-0000-4000-8000-000000000000/share-guest", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/items/{id}/share-guest. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/items/*/share-guest", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "items.guest_shares.list", "title": "Items Guest Shares List", "description": "Execute Items Guest Shares List in Topolo Roadmapper.", "method": "GET", "path": "/api/items/{id}/share-guest", "permission": "roadmaps:read", "readOnly": true, "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", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/items/00000000-0000-4000-8000-000000000000/share-guest", "body": null }, "effects": "Reads state through GET /api/items/{id}/share-guest without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/items/*/share-guest", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "items.guest_shares.revoke", "title": "Items Guest Shares Revoke", "description": "Execute Items Guest Shares Revoke in Topolo Roadmapper.", "method": "DELETE", "path": "/api/items/{id}/share-guest/{token}", "permission": "roadmaps:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 } }, "required": [ "id", "token" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "token": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/items/00000000-0000-4000-8000-000000000000/share-guest/example", "body": null }, "effects": "May change state through DELETE /api/items/{id}/share-guest/{token}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/items/*/share-guest/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "items.guest_shares.invite", "title": "Items Guest Shares Invite", "description": "Execute Items Guest Shares Invite in Topolo Roadmapper.", "method": "POST", "path": "/api/items/{id}/share-guest/{token}/invite-email", "permission": "roadmaps:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "recipientEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "id", "token", "recipientEmail" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "token": "example", "recipientEmail": "user@example.com" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/items/00000000-0000-4000-8000-000000000000/share-guest/example/invite-email", "body": { "id": "00000000-0000-4000-8000-000000000000", "token": "example", "recipientEmail": "user@example.com" } }, "effects": "May change state through POST /api/items/{id}/share-guest/{token}/invite-email. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/items/*/share-guest/*/invite-email", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "items.guest_scope.create", "title": "Items Guest Scope Create", "description": "Execute Items Guest Scope Create in Topolo Roadmapper.", "method": "POST", "path": "/api/items/guest/{scope}/items", "permission": "roadmaps:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "minLength": 1 }, "roadmapId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "blocked" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "assignee": { "type": "string", "maxLength": 255 }, "parentItemId": { "type": "string" } }, "required": [ "scope", "roadmapId", "name", "status", "priority" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "scope": "example", "roadmapId": "example", "name": "example", "status": "planned", "priority": "low" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/items/guest/example/items", "body": { "scope": "example", "roadmapId": "example", "name": "example", "status": "planned", "priority": "low" } }, "effects": "May change state through POST /api/items/guest/{scope}/items. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/items/guest/*/items", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "items.guest_scope.update", "title": "Items Guest Scope Update", "description": "Execute Items Guest Scope Update in Topolo Roadmapper.", "method": "PATCH", "path": "/api/items/guest/{scope}/items/{id}", "permission": "roadmaps:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "blocked" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "assignee": { "type": "string", "maxLength": 255 }, "parentItemId": { "type": "string" } }, "required": [ "scope", "id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "scope": "example", "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/items/guest/example/items/00000000-0000-4000-8000-000000000000", "body": { "scope": "example", "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PATCH /api/items/guest/{scope}/items/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/items/guest/*/items/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "roadmaps.list", "title": "Roadmaps List", "description": "Execute Roadmaps List in Topolo Roadmapper.", "method": "GET", "path": "/api/roadmaps", "permission": "roadmaps:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/roadmaps", "body": null }, "effects": "Reads state through GET /api/roadmaps without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/roadmaps", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "roadmaps.create", "title": "Roadmaps Create", "description": "Call POST /roadmaps.", "method": "POST", "path": "/api/roadmaps", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "projectId", "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Roadmaps Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "projectId": "example", "name": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/roadmaps", "body": { "projectId": "example", "name": "example" } }, "effects": "May change state through POST /api/roadmaps. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/roadmaps", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "roadmaps.update", "title": "Roadmaps Update", "description": "Call PUT /roadmaps/{id}.", "method": "PUT", "path": "/api/roadmaps/{id}", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "status": { "type": "string", "enum": [ "active", "completed", "archived" ] } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Roadmaps Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/roadmaps/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PUT /api/roadmaps/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/roadmaps/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "roadmaps.delete", "title": "Roadmaps Delete", "description": "Call DELETE /roadmaps/{id}.", "method": "DELETE", "path": "/api/roadmaps/{id}", "permission": "roadmaps:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Roadmaps Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/roadmaps/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/roadmaps/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/roadmaps/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "roadmaps.presentations.generate", "title": "Roadmaps Presentations Generate", "description": "Call POST /roadmaps/{id}/presentations/generate.", "method": "POST", "path": "/api/roadmaps/{id}/presentations/generate", "permission": "reports:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "template": { "type": "string", "enum": [ "executive_status_update", "steering_committee_review", "program_increment_review", "customer_safe_roadmap_update", "delivery_risk_review" ] }, "scenarioId": { "type": "string" }, "liveLinked": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Roadmaps Presentations Generate.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/roadmaps/00000000-0000-4000-8000-000000000000/presentations/generate", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/roadmaps/{id}/presentations/generate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/roadmaps/*/presentations/generate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "roadmaps.guest_shares.create", "title": "Roadmaps Guest Shares Create", "description": "Execute Roadmaps Guest Shares Create in Topolo Roadmapper.", "method": "POST", "path": "/api/roadmaps/{id}/share-guest", "permission": "roadmaps:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "expiresInHours": { "anyOf": [ { "type": "number", "minimum": 1, "maximum": 720 }, { "type": "null" } ] }, "accessMode": { "type": "string", "enum": [ "view", "edit" ] }, "allowItemNavigation": { "type": "boolean" }, "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/roadmaps/00000000-0000-4000-8000-000000000000/share-guest", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/roadmaps/{id}/share-guest. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/roadmaps/*/share-guest", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "roadmaps.guest_shares.list", "title": "Roadmaps Guest Shares List", "description": "Execute Roadmaps Guest Shares List in Topolo Roadmapper.", "method": "GET", "path": "/api/roadmaps/{id}/share-guest", "permission": "roadmaps:read", "readOnly": true, "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", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/roadmaps/00000000-0000-4000-8000-000000000000/share-guest", "body": null }, "effects": "Reads state through GET /api/roadmaps/{id}/share-guest without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/roadmaps/*/share-guest", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "roadmaps.guest_shares.revoke", "title": "Roadmaps Guest Shares Revoke", "description": "Execute Roadmaps Guest Shares Revoke in Topolo Roadmapper.", "method": "DELETE", "path": "/api/roadmaps/{id}/share-guest/{token}", "permission": "roadmaps:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 } }, "required": [ "id", "token" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "token": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/roadmaps/00000000-0000-4000-8000-000000000000/share-guest/example", "body": null }, "effects": "May change state through DELETE /api/roadmaps/{id}/share-guest/{token}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/roadmaps/*/share-guest/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "roadmaps.guest_shares.invite", "title": "Roadmaps Guest Shares Invite", "description": "Execute Roadmaps Guest Shares Invite in Topolo Roadmapper.", "method": "POST", "path": "/api/roadmaps/{id}/share-guest/{token}/invite-email", "permission": "roadmaps:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "recipientEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "id", "token", "recipientEmail" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "token": "example", "recipientEmail": "user@example.com" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/roadmaps/00000000-0000-4000-8000-000000000000/share-guest/example/invite-email", "body": { "id": "00000000-0000-4000-8000-000000000000", "token": "example", "recipientEmail": "user@example.com" } }, "effects": "May change state through POST /api/roadmaps/{id}/share-guest/{token}/invite-email. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/roadmaps/*/share-guest/*/invite-email", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "dependencies.create", "title": "Dependencies Create", "description": "Call POST /dependencies.", "method": "POST", "path": "/api/dependencies", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fromItemId": { "type": "string", "minLength": 1 }, "toItemId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "blocks", "requires", "related" ] } }, "required": [ "fromItemId", "toItemId", "type" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Dependencies Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "fromItemId": "example", "toItemId": "example", "type": "blocks" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/dependencies", "body": { "fromItemId": "example", "toItemId": "example", "type": "blocks" } }, "effects": "May change state through POST /api/dependencies. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/dependencies", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "dependencies.delete", "title": "Dependencies Delete", "description": "Call DELETE /dependencies/{id}.", "method": "DELETE", "path": "/api/dependencies/{id}", "permission": "roadmaps:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Dependencies Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/dependencies/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/dependencies/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/dependencies/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "comments.create", "title": "Comments Create", "description": "Call POST /comments.", "method": "POST", "path": "/api/comments", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "roadmapItemId": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 }, "mentionedUserIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "maxItems": 50 } }, "required": [ "roadmapItemId", "content" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Comments Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "roadmapItemId": "example", "content": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/comments", "body": { "roadmapItemId": "example", "content": "example" } }, "effects": "May change state through POST /api/comments. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/comments", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "comments.update", "title": "Comments Update", "description": "Call PUT /comments/{commentId}.", "method": "PUT", "path": "/api/comments/{commentId}", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "commentId": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 } }, "required": [ "commentId", "content" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Comments Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "commentId": "example", "content": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/comments/example", "body": { "commentId": "example", "content": "example" } }, "effects": "May change state through PUT /api/comments/{commentId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/comments/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "comments.delete", "title": "Comments Delete", "description": "Call DELETE /comments/{commentId}.", "method": "DELETE", "path": "/api/comments/{commentId}", "permission": "roadmaps:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "commentId": { "type": "string", "minLength": 1 } }, "required": [ "commentId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Comments Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "commentId": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/comments/example", "body": null }, "effects": "May change state through DELETE /api/comments/{commentId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/comments/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "attachments.upload", "title": "Attachments Upload", "description": "Call POST /attachments/upload.", "method": "POST", "path": "/api/attachments/upload", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "roadmapItemId": { "type": "string", "minLength": 1 }, "fileName": { "type": "string", "minLength": 1 }, "contentType": { "type": "string", "minLength": 1 }, "base64": { "type": "string", "minLength": 1, "maxLength": 14000000 } }, "required": [ "roadmapItemId", "fileName", "contentType", "base64" ], "additionalProperties": false }, "agentContract": { "upload": { "profile": "inline-base64", "contentField": "base64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 10485760, "acceptedContentTypes": [ "*/*" ] } }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Attachments Upload.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "roadmapItemId": "example", "fileName": "example", "contentType": "example", "base64": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/attachments/upload", "body": { "roadmapItemId": "example", "fileName": "example", "contentType": "example", "base64": "example" } }, "effects": "May change state through POST /api/attachments/upload. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/attachments/upload", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "attachments.delete", "title": "Attachments Delete", "description": "Call DELETE /attachments/{attachmentId}.", "method": "DELETE", "path": "/api/attachments/{attachmentId}", "permission": "roadmaps:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "attachmentId": { "type": "string", "minLength": 1 } }, "required": [ "attachmentId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Attachments Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "attachmentId": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/attachments/example", "body": null }, "effects": "May change state through DELETE /api/attachments/{attachmentId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/attachments/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "reports.generate", "title": "Reports Generate", "description": "Call POST /reports/generate.", "method": "POST", "path": "/api/reports/generate", "permission": "reports:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "filters": { "type": "object", "properties": { "projectIds": { "type": "array", "items": { "type": "string" } }, "roadmapIds": { "type": "array", "items": { "type": "string" } }, "statuses": { "type": "array", "items": { "type": "string" } }, "priorities": { "type": "array", "items": { "type": "string" } }, "dateRange": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": false }, "assignees": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "required": [ "title", "filters" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Reports Generate.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "title": "example", "filters": { "projectIds": [ "example" ], "roadmapIds": [ "example" ], "statuses": [ "example" ] } }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/reports/generate", "body": { "title": "example", "filters": { "projectIds": [ "example" ], "roadmapIds": [ "example" ], "statuses": [ "example" ] } } }, "effects": "May change state through POST /api/reports/generate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/reports/generate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "imports.csv", "title": "Imports Csv", "description": "Execute Imports Csv in Topolo Roadmapper.", "method": "POST", "path": "/api/import", "permission": "roadmaps:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "csv": { "type": "string", "minLength": 1 }, "importType": { "type": "string", "enum": [ "roadmaps", "projects", "combined" ] } }, "required": [ "csv" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "csv": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/import", "body": { "csv": "example" } }, "effects": "May change state through POST /api/import. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/import", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "planning.sessions.delete", "title": "Planning Sessions Delete", "description": "Call DELETE /planning/sessions/{id}.", "method": "DELETE", "path": "/api/planning/sessions/{id}", "permission": "roadmaps:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Planning Sessions Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/planning/sessions/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "May change state through DELETE /api/planning/sessions/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/planning/sessions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "planning.turns.create", "title": "Planning Turns Create", "description": "Call POST /planning/sessions/{id}/turns.", "method": "POST", "path": "/api/planning/sessions/{id}/turns", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1, "maxLength": 4000 }, "document": {} }, "required": [ "id", "message" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Planning Turns Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "message": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/planning/sessions/00000000-0000-4000-8000-000000000000/turns", "body": { "id": "00000000-0000-4000-8000-000000000000", "message": "example" } }, "effects": "May change state through POST /api/planning/sessions/{id}/turns. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/planning/sessions/*/turns", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "planning.scenarios.create", "title": "Planning Scenarios Create", "description": "Call POST /planning/sessions/{id}/scenarios.", "method": "POST", "path": "/api/planning/sessions/{id}/scenarios", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "document": {} }, "required": [ "id", "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Planning Scenarios Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "name": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/planning/sessions/00000000-0000-4000-8000-000000000000/scenarios", "body": { "id": "00000000-0000-4000-8000-000000000000", "name": "example" } }, "effects": "May change state through POST /api/planning/sessions/{id}/scenarios. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/planning/sessions/*/scenarios", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "planning.apply", "title": "Planning Apply", "description": "Call POST /planning/sessions/{id}/apply.", "method": "POST", "path": "/api/planning/sessions/{id}/apply", "permission": "roadmaps:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "document": {} }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Planning Apply.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/planning/sessions/00000000-0000-4000-8000-000000000000/apply", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through POST /api/planning/sessions/{id}/apply. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/planning/sessions/*/apply", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "presentations.update", "title": "Presentations Update", "description": "Call PATCH /presentations/{id}.", "method": "PATCH", "path": "/api/presentations/{id}", "permission": "reports:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "summary": { "type": "string", "maxLength": 1200 }, "slides": { "type": "array", "items": {} } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Presentations Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/presentations/00000000-0000-4000-8000-000000000000", "body": { "id": "00000000-0000-4000-8000-000000000000" } }, "effects": "May change state through PATCH /api/presentations/{id}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/presentations/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "presentations.export", "title": "Presentations Export", "description": "Call POST /presentations/{id}/export.", "method": "POST", "path": "/api/presentations/{id}/export", "permission": "reports:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "web", "pptx" ] } }, "required": [ "id", "format" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Presentations Export.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000", "format": "web" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/presentations/00000000-0000-4000-8000-000000000000/export", "body": { "id": "00000000-0000-4000-8000-000000000000", "format": "web" } }, "effects": "May change state through POST /api/presentations/{id}/export. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/presentations/*/export", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "Workspaces Archive", "description": "Archive an empty Roadmapper workspace: Roadmapper confirms it holds no planning data, then asks the platform to archive it.", "method": "DELETE", "path": "/api/roadmapper/workspaces/{workspaceId}", "permission": "workspace:delete", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/roadmapper/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/roadmapper/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/roadmapper/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "projects:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "projects.get", "title": "Projects Get", "description": "Call GET /projects/{id}.", "method": "GET", "path": "/api/projects/{id}", "permission": "projects:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/projects/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/projects/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/projects/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.dashboard.get", "title": "Projects Dashboard Get", "description": "Call GET /projects/{id}/dashboard.", "method": "GET", "path": "/api/projects/{id}/dashboard", "permission": "projects:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Dashboard Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/projects/00000000-0000-4000-8000-000000000000/dashboard", "body": null }, "effects": "Reads state through GET /api/projects/{id}/dashboard without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/projects/*/dashboard", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.planning_feed.get", "title": "Projects Planning Feed Get", "description": "Call GET /projects/{id}/planning-feed.", "method": "GET", "path": "/api/projects/{id}/planning-feed", "permission": "projects:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Planning Feed Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/projects/00000000-0000-4000-8000-000000000000/planning-feed", "body": null }, "effects": "Reads state through GET /api/projects/{id}/planning-feed without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/projects/*/planning-feed", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.planning_sessions.list", "title": "Projects Planning Sessions List", "description": "Call GET /projects/{id}/planning/sessions.", "method": "GET", "path": "/api/projects/{id}/planning/sessions", "permission": "roadmaps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Planning Sessions List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/projects/00000000-0000-4000-8000-000000000000/planning/sessions", "body": null }, "effects": "Reads state through GET /api/projects/{id}/planning/sessions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/projects/*/planning/sessions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.ai_status.get", "title": "Projects Ai Status Get", "description": "Call GET /projects/ai/status.", "method": "GET", "path": "/api/projects/ai/status", "permission": "roadmaps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Ai Status Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/projects/ai/status", "body": null }, "effects": "Reads state through GET /api/projects/ai/status without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/projects/ai/status", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.ai_sessions.list", "title": "Projects Ai Sessions List", "description": "Call GET /projects/ai/sessions.", "method": "GET", "path": "/api/projects/ai/sessions", "permission": "roadmaps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Ai Sessions List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/projects/ai/sessions", "body": null }, "effects": "Reads state through GET /api/projects/ai/sessions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/projects/ai/sessions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.ai_sessions.get", "title": "Projects Ai Sessions Get", "description": "Call GET /projects/ai/sessions/{id}.", "method": "GET", "path": "/api/projects/ai/sessions/{id}", "permission": "roadmaps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Ai Sessions Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/projects/ai/sessions/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/projects/ai/sessions/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/projects/ai/sessions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "items.get", "title": "Items Get", "description": "Call GET /items/{id}.", "method": "GET", "path": "/api/items/{id}", "permission": "roadmaps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Items Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/items/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/items/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/items/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "roadmaps.get", "title": "Roadmaps Get", "description": "Call GET /roadmaps/{id}.", "method": "GET", "path": "/api/roadmaps/{id}", "permission": "roadmaps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Roadmaps Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/roadmaps/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/roadmaps/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/roadmaps/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "roadmaps.items.list", "title": "Roadmaps Items List", "description": "Call GET /roadmaps/{id}/items.", "method": "GET", "path": "/api/roadmaps/{id}/items", "permission": "roadmaps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Roadmaps Items List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/roadmaps/00000000-0000-4000-8000-000000000000/items", "body": null }, "effects": "Reads state through GET /api/roadmaps/{id}/items without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/roadmaps/*/items", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "dependencies.item.list", "title": "Dependencies Item List", "description": "Call GET /dependencies/item/{id}.", "method": "GET", "path": "/api/dependencies/item/{id}", "permission": "roadmaps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Dependencies Item List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/dependencies/item/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/dependencies/item/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/dependencies/item/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "comments.by_roadmap_item.list", "title": "Comments By Roadmap Item List", "description": "Call GET /comments/roadmap-item/{roadmapItemId}.", "method": "GET", "path": "/api/comments/roadmap-item/{roadmapItemId}", "permission": "roadmaps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "roadmapItemId": { "type": "string", "minLength": 1 } }, "required": [ "roadmapItemId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Comments By Roadmap Item List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "roadmapItemId": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/comments/roadmap-item/example", "body": null }, "effects": "Reads state through GET /api/comments/roadmap-item/{roadmapItemId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/comments/roadmap-item/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "attachments.by_roadmap_item.list", "title": "Attachments By Roadmap Item List", "description": "Call GET /attachments/roadmap-item/{roadmapItemId}.", "method": "GET", "path": "/api/attachments/roadmap-item/{roadmapItemId}", "permission": "roadmaps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "roadmapItemId": { "type": "string", "minLength": 1 }, "includeDescendants": { "type": "string", "enum": [ "true", "false" ] } }, "required": [ "roadmapItemId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Attachments By Roadmap Item List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "roadmapItemId": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/attachments/roadmap-item/example", "body": null }, "effects": "Reads state through GET /api/attachments/roadmap-item/{roadmapItemId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/attachments/roadmap-item/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "attachments.by_roadmap.list", "title": "Attachments By Roadmap List", "description": "Call GET /attachments/roadmap/{roadmapId}.", "method": "GET", "path": "/api/attachments/roadmap/{roadmapId}", "permission": "roadmaps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "roadmapId": { "type": "string", "minLength": 1 } }, "required": [ "roadmapId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Attachments By Roadmap List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "roadmapId": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/attachments/roadmap/example", "body": null }, "effects": "Reads state through GET /api/attachments/roadmap/{roadmapId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/attachments/roadmap/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "attachments.download", "title": "Attachments Download", "description": "Call GET /attachments/{attachmentId}/download.", "method": "GET", "path": "/api/attachments/{attachmentId}/download", "permission": "roadmaps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "attachmentId": { "type": "string", "minLength": 1 } }, "required": [ "attachmentId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Attachments Download.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "attachmentId": "example" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/attachments/example/download", "body": null }, "effects": "Reads state through GET /api/attachments/{attachmentId}/download without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/attachments/*/download", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "planning.sessions.get", "title": "Planning Sessions Get", "description": "Call GET /planning/sessions/{id}.", "method": "GET", "path": "/api/planning/sessions/{id}", "permission": "roadmaps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Planning Sessions Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/planning/sessions/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/planning/sessions/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/planning/sessions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "planning.revisions.list", "title": "Planning Revisions List", "description": "Call GET /planning/sessions/{id}/revisions.", "method": "GET", "path": "/api/planning/sessions/{id}/revisions", "permission": "roadmaps:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Planning Revisions List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/planning/sessions/00000000-0000-4000-8000-000000000000/revisions", "body": null }, "effects": "Reads state through GET /api/planning/sessions/{id}/revisions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/planning/sessions/*/revisions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "presentations.get", "title": "Presentations Get", "description": "Call GET /presentations/{id}.", "method": "GET", "path": "/api/presentations/{id}", "permission": "reports:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Presentations Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-roadmapper --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/presentations/00000000-0000-4000-8000-000000000000", "body": null }, "effects": "Reads state through GET /api/presentations/{id} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/presentations/*", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 84, "matched_actions": 74, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 10, "configured_exclusions": 6, "configuration_findings": [], "notes": [ "5 manually-declared route(s)" ] }, "runtime_contract_audit": { "status": "verified", "actions": 74, "contracts": 74, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/index.ts" ], "authorization_sources": [ "apps/api/src/index.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloRoadmapper/topolo.mobile-experience.json", "contract": { "version": "1.0.0", "status": "published", "mode": "native_capability", "appId": "app_topolo_roadmapper", "localizationNamespace": "roadmapper", "permissions": [ "projects:read", "projects:write", "roadmaps:read", "roadmaps:write" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/projects", "auth": { "audience": "topolo-roadmapper", "scopes": [ "projects:read", "projects:write", "roadmaps:read", "roadmaps:write" ] }, "routes": [ { "path": "/projects", "apiPath": "/api/projects", "title": "Projects", "titleKey": "roadmapper.nav.projects", "template": "record.list", "dataSource": "roadmapper.projects.list", "detailRoute": "/projects/:id" }, { "path": "/projects/:id", "apiPath": "/api/projects/:id", "title": "Project", "titleKey": "roadmapper.pages.projects.id.project", "template": "record.detail", "dataSource": "roadmapper.projects.detail" }, { "path": "/roadmaps", "apiPath": "/api/roadmaps", "title": "Roadmaps", "titleKey": "roadmapper.nav.roadmaps", "template": "record.list", "dataSource": "roadmapper.roadmaps.list", "detailRoute": "/roadmaps/:id" }, { "path": "/roadmaps/:id", "apiPath": "/api/roadmaps/:id", "title": "Roadmap", "titleKey": "roadmapper.pages.roadmaps.roadmap", "template": "record.detail", "dataSource": "roadmapper.roadmaps.detail" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "ALL", "path": "/health", "source_path": "apps/TopoloRoadmapper/apps/api/src/index.ts" }, { "method": "ALL", "path": "/api/widget", "source_path": "apps/TopoloRoadmapper/apps/api/src/index.ts" }, { "method": "ALL", "path": "/", "source_path": "apps/TopoloRoadmapper/apps/api/src/index.ts" } ], "ui_routes": [ { "path": "/dashboard", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/calendar", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/projects", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/projects/new", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/projects/new/manual", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/projects/:id", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/projects/:id/dashboard", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/roadmaps", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/roadmaps/new", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/roadmaps/:id", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/roadmap-items/:id", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/presentations/:id", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/settings", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/settings/:section", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/import", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/export", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/reports", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/projects/guest/:token", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/roadmaps/guest/:token", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/roadmap-items/guest/:token", "source_path": "apps/TopoloRoadmapper/apps/web/src/App.tsx" }, { "path": "/dashboard", "source_path": "apps/TopoloRoadmapper/apps/web/src/app-routes.tsx" }, { "path": "/calendar", "source_path": "apps/TopoloRoadmapper/apps/web/src/app-routes.tsx" }, { "path": "/projects", "source_path": "apps/TopoloRoadmapper/apps/web/src/app-routes.tsx" }, { "path": "/roadmaps", "source_path": "apps/TopoloRoadmapper/apps/web/src/app-routes.tsx" }, { "path": "/reports", "source_path": "apps/TopoloRoadmapper/apps/web/src/app-routes.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/roadmapper", "internal/apps/roadmapper" ], "present_paths": [ "applications/roadmapper", "internal/apps/roadmapper" ], "missing_paths": [], "human_reference": "/systems/topolo-roadmapper", "machine_reference": "/machine/systems/topolo-roadmapper.json", "action_examples": 74, "action_schemas": 74 }, "source_findings": [] }, "topolo-social-studio": { "id": "topolo-social-studio", "name": "Social Studio", "slug": "topolo-social-studio", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloSocialStudio" ], "source_revisions": [ { "source_path": "apps/TopoloSocialStudio", "repository": "apps/TopoloSocialStudio", "revision": "e59a4cb80a4e7154108acb7133a5127016e6540c", "ref": "origin/staging" } ], "source_counts": { "source_files": 138, "test_files": 87, "test_cases": 0, "migration_files": 12, "database_tables": 0, "manifests": 1, "deploy_targets": 3, "actions": 47, "mobile_contracts": 1, "notifications": 6, "package_manifests": 13, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloSocialStudio/topolo.app.json", "service_slug": "topolo-social-studio", "name": "topolo-social-studio", "app_id": "app_topolo_social_studio", "compatibility_date": "2026-04-10", "primary_target": null, "environments": [ "development", "production", "staging" ], "targets": [ { "name": "marketing", "kind": "worker", "directory": "apps/marketing", "main": "src/worker.ts", "worker_name": "topolo-social-studio", "subdomain": "studio", "healthcheck_path": null, "variable_names": [ "AUTH_API_URL" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null } ] }, { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/index.ts", "worker_name": "topolo-social-studio-api", "subdomain": null, "healthcheck_path": "/healthz", "variable_names": [ "ADDITIONAL_ALLOWED_ORIGINS", "API_WORKER_URL", "APP_ENV", "AUTH_BASE_URL", "BILLING_SUPPORT_CONTACT", "DESKTOP_APP_URL", "ENVIRONMENT", "GENERATION_QUEUE_NAME", "MARKETING_APP_URL", "QUEUE_CONSUMER_NAME", "SOCIAL_STUDIO_PUBLIC_BASE_URL", "TOPOLO_BUG_REPORTER_URL", "TOPOLO_LAUNCHER_URL", "TOPOLO_NOTIFY_URL", "TOPOLO_SEED_APP_ID" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "BRAND_API", "target": null }, { "kind": "d1", "binding": "STUDIO_CORE_DB", "target": null }, { "kind": "d1", "binding": "STUDIO_GENERATION_DB", "target": null }, { "kind": "d1", "binding": "STUDIO_USAGE_DB", "target": null }, { "kind": "d1", "binding": "STUDIO_CONTROLS_DB", "target": null }, { "kind": "r2", "binding": "ASSET_BUCKET", "target": null } ] }, { "name": "jobs", "kind": "worker", "directory": "apps/jobs", "main": "src/index.ts", "worker_name": "topolo-social-studio-queue", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "APP_ENV", "AUTH_BASE_URL", "DESKTOP_SYNC_QUEUE", "GENERATION_QUEUE_NAME", "QUEUE_CONSUMER_NAME", "SOCIAL_STUDIO_PUBLIC_BASE_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "STUDIO_CORE_DB", "target": null }, { "kind": "d1", "binding": "STUDIO_GENERATION_DB", "target": null }, { "kind": "d1", "binding": "STUDIO_USAGE_DB", "target": null }, { "kind": "d1", "binding": "STUDIO_CONTROLS_DB", "target": null }, { "kind": "r2", "binding": "ASSET_BUCKET", "target": null } ] } ], "notifications": [ "social_studio.approval.requested", "social_studio.asset.ready", "social_studio.generation.completed", "social_studio.generation.failed", "social_studio.plan.ready", "social_studio.quota.warning" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_social_studio", "events": [ { "type": "social_studio.approval.requested", "version": 1, "status": "published", "description": "A project approval request was persisted for an active workspace reviewer.", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "required": [ "approval_request_id", "project_id", "requested_by_user_id" ], "properties": { "approval_request_id": { "type": "string" }, "project_id": { "type": "string" }, "requested_by_user_id": { "type": "string" }, "note": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "additionalProperties": true }, "examples": [ { "title": "Approval requested", "body": "A Social Studio project is ready for your review.", "object_id": "approval_123", "occurred_at": "2026-07-20T00:00:00.000Z", "payload": { "approval_request_id": "approval_123", "project_id": "project_123", "requested_by_user_id": "user_123", "note": "Please review" } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^social-studio:approval:.*:requested$" }, "sensitiveFields": [] }, { "type": "social_studio.asset.ready", "version": 1, "status": "published", "description": "A generated asset was durably persisted in the available state.", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "required": [ "asset_id", "job_id", "project_id", "scene_id", "kind" ], "properties": { "asset_id": { "type": "string" }, "job_id": { "type": "string" }, "project_id": { "type": "string" }, "scene_id": { "type": "string" }, "kind": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "examples": [ { "title": "Asset ready", "body": "Hero image is ready to review.", "object_id": "asset_123", "occurred_at": "2026-07-20T00:00:00.000Z", "payload": { "asset_id": "asset_123", "job_id": "job_123", "project_id": "project_123", "scene_id": "scene_123", "kind": "image" } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^social-studio:asset:.*:ready$" }, "sensitiveFields": [] }, { "type": "social_studio.generation.completed", "version": 1, "status": "published", "description": "A scene generation job durably reached the completed terminal state.", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "required": [ "job_id", "project_id", "scene_id", "asset_count" ], "properties": { "job_id": { "type": "string" }, "project_id": { "type": "string" }, "scene_id": { "type": "string" }, "asset_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } }, "additionalProperties": true }, "examples": [ { "title": "Generation completed", "body": "2 generated assets are ready.", "object_id": "job_123", "occurred_at": "2026-07-20T00:00:00.000Z", "payload": { "job_id": "job_123", "project_id": "project_123", "scene_id": "scene_123", "asset_count": 2 } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^social-studio:generation:.*:completed$" }, "sensitiveFields": [] }, { "type": "social_studio.generation.failed", "version": 1, "status": "published", "description": "A scene generation job durably reached the failed terminal state after retries were exhausted.", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "required": [ "job_id", "project_id", "scene_id", "provider", "error_code" ], "properties": { "job_id": { "type": "string" }, "project_id": { "type": "string" }, "scene_id": { "type": "string" }, "provider": { "type": "string" }, "error_code": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "examples": [ { "title": "Generation failed", "body": "A Social Studio generation job needs attention.", "object_id": "job_123", "occurred_at": "2026-07-20T00:00:00.000Z", "payload": { "job_id": "job_123", "project_id": "project_123", "scene_id": "scene_123", "provider": "nexus-configured", "error_code": "provider_timeout" } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^social-studio:generation:.*:failed$" }, "sensitiveFields": [] }, { "type": "social_studio.plan.ready", "version": 1, "status": "published", "description": "A creative plan and its scenes were durably persisted and are ready for review.", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "required": [ "project_id", "plan_id", "scene_count" ], "properties": { "project_id": { "type": "string" }, "plan_id": { "type": [ "string", "null" ] }, "scene_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": true } }, "additionalProperties": true }, "examples": [ { "title": "Creative plan ready", "body": "4 planned scenes are ready to review.", "object_id": "plan_123", "occurred_at": "2026-07-20T00:00:00.000Z", "payload": { "project_id": "project_123", "plan_id": "plan_123", "scene_count": 4 } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^social-studio:plan:.*:ready:" }, "sensitiveFields": [] }, { "type": "social_studio.quota.warning", "version": 1, "status": "published", "description": "A monthly deduplicated entitlement warning was durably claimed for a workspace member.", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "payload" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "required": [ "warning_id", "action", "warning", "period_key" ], "properties": { "warning_id": { "type": "string" }, "action": { "type": "string" }, "warning": { "type": "string" }, "period_key": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "examples": [ { "title": "Usage limit warning", "body": "generation_units will exceed the included plan limit.", "object_id": "quota_warning_123", "occurred_at": "2026-07-20T00:00:00.000Z", "payload": { "warning_id": "quota_warning_123", "action": "generation.start", "warning": "generation_units will exceed the included plan limit.", "period_key": "2026-07" } } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^social-studio:quota-warning:" }, "sensitiveFields": [] } ] }, "actions": [ { "name": "organizations.data.export", "title": "Export organization data", "description": "Export all Social Studio data and asset object metadata owned by the authenticated organization across four D1 stores without credentials.", "method": "GET", "path": "/api/organizations/data/export", "permission": "privacy:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/data/export", "body": null }, "effects": "Reads state through GET /api/organizations/data/export without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/data/export", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.erase", "title": "Erase organization data", "description": "Permanently erase all Social Studio data and asset objects owned by the authenticated organization while retaining backups under policy.", "method": "DELETE", "path": "/api/organizations/data/erase", "permission": "privacy:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/data/erase", "body": null }, "effects": "May change state through DELETE /api/organizations/data/erase. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/data/erase", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "Delete workspace", "description": "Delete a non-default empty Social Studio workspace.", "method": "DELETE", "path": "/api/workspaces/{workspaceSlug}", "permission": "workspace:delete", "authorizationMode": "static", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceSlug": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/workspaces/example", "body": null }, "effects": "May change state through DELETE /api/workspaces/{workspaceSlug}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.create", "title": "Create project", "description": "Create a Social Studio project.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/projects", "permission": "workspace:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "objective": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "templateId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brandKitId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "workspaceSlug", "title" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create project.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "title": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/projects", "body": { "workspaceSlug": "example", "title": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/projects. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/projects", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.duplicate", "title": "Duplicate project", "description": "Duplicate a Social Studio project.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/duplicate", "permission": "briefs:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "includeAssets": { "type": "boolean" } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Duplicate project.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/projects/example/duplicate", "body": { "workspaceSlug": "example", "projectId": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/duplicate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/projects/*/duplicate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "planning.generate", "title": "Generate project plan", "description": "Generate a project creative plan.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/planning/generate", "permission": "briefs:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "freeformPrompt": { "type": "string", "minLength": 1, "maxLength": 20000 }, "title": { "type": "string", "maxLength": 255 }, "platforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "youtube", "linkedin", "x", "facebook" ] } }, "durationMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 180000 }, "style": { "type": "string", "maxLength": 4000 }, "captions": { "type": "string", "enum": [ "auto", "manual", "none" ] }, "objective": { "type": "string", "maxLength": 4000 }, "audience": { "type": "string", "maxLength": 4000 } }, "required": [ "workspaceSlug", "projectId", "freeformPrompt" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Generate project plan.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example", "freeformPrompt": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/projects/example/planning/generate", "body": { "workspaceSlug": "example", "projectId": "example", "freeformPrompt": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/planning/generate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/projects/*/planning/generate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.approval_requests.create", "title": "Create project approval request", "description": "Request approval from an active Social Studio workspace member.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/approval-requests", "permission": "approvals:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "reviewerUserId": { "type": "string", "minLength": 1 }, "note": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } }, "required": [ "workspaceSlug", "projectId", "reviewerUserId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Persisted approval request.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example", "reviewerUserId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/projects/example/approval-requests", "body": { "workspaceSlug": "example", "projectId": "example", "reviewerUserId": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/approval-requests. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/projects/*/approval-requests", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "generation.start", "title": "Start generation", "description": "Start generation for a project.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/generation/start", "permission": "generation:write", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "sceneIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "provider": { "type": "string", "enum": [ "nexus-configured", "grok-imagine", "nano-banana", "cloudflare-media" ] }, "fallbackProvider": { "anyOf": [ { "type": "string", "enum": [ "nexus-configured", "grok-imagine", "nano-banana", "cloudflare-media" ] }, { "type": "null" } ] }, "candidateCount": { "type": "integer", "minimum": 1, "maximum": 4 }, "sourceAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outputKind": { "type": "string", "enum": [ "image", "video" ] }, "videoDurationSeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 15 }, { "type": "null" } ] }, "nexusProviderOverride": { "anyOf": [ { "type": "string", "enum": [ "openai", "google", "xai", "cloudflare" ] }, { "type": "null" } ] }, "nexusModelOverride": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Start generation.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/projects/example/generation/start", "body": { "workspaceSlug": "example", "projectId": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/generation/start. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/projects/*/generation/start", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operator.backup_export", "title": "Get backup export", "description": "Get a complete owner-only Social Studio workspace export.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/operator/backup-export", "permission": "exports:read", "readOnly": true, "requiresConfirmation": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get backup export.", "additionalProperties": true }, "destructive": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "workspaceSlug": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/operator/backup-export", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/operator/backup-export without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/operator/backup-export", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "billing.entitlements.check", "title": "Billing Entitlements Check", "description": "Call POST /api/workspaces/{workspaceSlug}/billing/entitlements/check.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/billing/entitlements/check", "permission": "workspace:read", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "action": { "type": "string", "enum": [ "project.create", "planning.generate", "generation.start", "generation.regenerate", "render.create", "billing.portal", "usage.reconcile", "brand_kits.use", "batch_variants.use" ] }, "requestedGenerationUnits": { "type": "number", "minimum": 0 }, "requestedRenderJobs": { "type": "number", "minimum": 0 }, "requestedStorageBytes": { "type": "number", "minimum": 0 }, "featureKey": { "type": "string", "enum": [ "batch_variants", "brand_kits", "priority_render", "billing_portal", "operator_reconciliation" ] } }, "required": [ "workspaceSlug", "action" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Billing Entitlements Check.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "action": "project.create" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/billing/entitlements/check", "body": { "workspaceSlug": "example", "action": "project.create" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/billing/entitlements/check. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/billing/entitlements/check", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "billing.portal_session.create", "title": "Billing Portal Session Create", "description": "Call POST /api/workspaces/{workspaceSlug}/billing/portal-session.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/billing/portal-session", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Billing Portal Session Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/billing/portal-session", "body": { "workspaceSlug": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/billing/portal-session. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/billing/portal-session", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "billing.reconciliations.create", "title": "Billing Reconciliations Create", "description": "Call POST /api/workspaces/{workspaceSlug}/billing/reconciliations.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/billing/reconciliations", "permission": "approvals:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "metricKey": { "type": "string", "enum": [ "generation_units", "storage_bytes", "render_jobs", "premium_batch_variants", "premium_brand_kits" ] }, "quantityDelta": { "type": "number" }, "unit": { "type": "string", "minLength": 1, "maxLength": 64 }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "workspaceSlug", "metricKey", "quantityDelta", "unit", "reason", "description" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Billing Reconciliations Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "workspaceSlug": "example", "metricKey": "generation_units", "quantityDelta": 1, "unit": "example", "reason": "example", "description": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/billing/reconciliations", "body": { "workspaceSlug": "example", "metricKey": "generation_units", "quantityDelta": 1, "unit": "example", "reason": "example", "description": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/billing/reconciliations. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/billing/reconciliations", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "billing.subscription.update", "title": "Billing Subscription Update", "description": "Call PATCH /api/workspaces/{workspaceSlug}/billing/subscription.", "method": "PATCH", "path": "/api/workspaces/{workspaceSlug}/billing/subscription", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "planKey": { "type": "string", "enum": [ "free", "trial", "pro", "agency" ] }, "status": { "type": "string", "enum": [ "trialing", "active", "grace_period", "past_due", "suspended", "cancelled" ] }, "supportPlanLabel": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "invoiceEmail": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "providerCustomerId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "providerSubscriptionId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "workspaceSlug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Billing Subscription Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "workspaceSlug": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/workspaces/example/billing/subscription", "body": { "workspaceSlug": "example" } }, "effects": "May change state through PATCH /api/workspaces/{workspaceSlug}/billing/subscription. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/workspaces/*/billing/subscription", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "telemetry.events.create", "title": "Telemetry Events Create", "description": "Call POST /api/workspaces/{workspaceSlug}/telemetry/events.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/telemetry/events", "permission": "workspace:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "stream": { "type": "string", "enum": [ "product", "operational", "security", "audit" ] }, "channel": { "type": "string", "enum": [ "worker", "queue", "desktop", "web" ] }, "eventName": { "type": "string", "enum": [ "app.opened", "auth.login.success", "auth.login.failure", "project.created", "project.duplicated", "project.deleted", "template.applied", "brief.generated", "creative_plan.generated", "scene.generated", "asset.generation.started", "asset.generation.succeeded", "asset.generation.failed", "caption.edited", "library.asset.saved", "library.asset.reused", "variants.generated", "render.preview.started", "render.preview.completed", "render.final_export.started", "render.final_export.completed", "billing.entitlement.denied", "billing.portal.opened", "billing.reconciliation.applied", "provider.retry.scheduled", "provider.normalization.failed", "provider.moderation.failed", "sync.failed", "rate_limit.triggered", "moderation.blocked", "security.audit.recorded" ] }, "status": { "type": "string", "enum": [ "success", "failure", "pending", "denied", "blocked", "review" ] }, "severity": { "type": "string", "enum": [ "info", "warning", "error", "critical" ] }, "correlationId": { "type": "string" }, "errorCode": { "anyOf": [ { "type": "string", "enum": [ "auth_failure", "billing_limit", "moderation_block", "provider_failure", "provider_retryable", "quota_failure", "rate_limit", "render_failure", "security_violation", "sync_failure", "unknown" ] }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "latencyMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "workspaceSlug", "stream", "channel", "eventName", "status", "severity" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Telemetry Events Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "stream": "product", "channel": "worker", "eventName": "app.opened", "status": "success", "severity": "info" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/telemetry/events", "body": { "workspaceSlug": "example", "stream": "product", "channel": "worker", "eventName": "app.opened", "status": "success", "severity": "info" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/telemetry/events. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/telemetry/events", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "assets.access_token.create", "title": "Assets Access Token Create", "description": "Call POST /api/workspaces/{workspaceSlug}/assets/{assetId}/access-token.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/assets/{assetId}/access-token", "permission": "assets:read", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "assetId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "assetId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Assets Access Token Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "assetId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/assets/example/access-token", "body": { "workspaceSlug": "example", "assetId": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/assets/{assetId}/access-token. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/assets/*/access-token", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "assets.library.save", "title": "Assets Library Save", "description": "Call POST /api/workspaces/{workspaceSlug}/assets/{assetId}/library.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/assets/{assetId}/library", "permission": "assets:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "assetId": { "type": "string", "minLength": 1 }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "string" } }, "favorite": { "type": "boolean" } }, "required": [ "workspaceSlug", "assetId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Assets Library Save.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "assetId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/assets/example/library", "body": { "workspaceSlug": "example", "assetId": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/assets/{assetId}/library. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/assets/*/library", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "library.assets.reuse", "title": "Library Assets Reuse", "description": "Call POST /api/workspaces/{workspaceSlug}/library/assets/{entryId}/reuse.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/library/assets/{entryId}/reuse", "permission": "assets:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "entryId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "sceneId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "workspaceSlug", "entryId", "projectId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Library Assets Reuse.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "entryId": "example", "projectId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/library/assets/example/reuse", "body": { "workspaceSlug": "example", "entryId": "example", "projectId": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/library/assets/{entryId}/reuse. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/library/assets/*/reuse", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "project_templates.create", "title": "Project Templates Create", "description": "Call POST /api/workspaces/{workspaceSlug}/project-templates.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/project-templates", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "promptDefaults": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "youtube", "linkedin", "x", "facebook" ] } } }, "required": [ "workspaceSlug", "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Project Templates Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "workspaceSlug": "example", "name": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/project-templates", "body": { "workspaceSlug": "example", "name": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/project-templates. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/project-templates", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "project_templates.update", "title": "Project Templates Update", "description": "Call PATCH /api/workspaces/{workspaceSlug}/project-templates/{templateId}.", "method": "PATCH", "path": "/api/workspaces/{workspaceSlug}/project-templates/{templateId}", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "promptDefaults": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "youtube", "linkedin", "x", "facebook" ] } }, "workspaceSlug": { "type": "string", "minLength": 1 }, "templateId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "workspaceSlug", "templateId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Project Templates Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "workspaceSlug": "example", "templateId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/workspaces/example/project-templates/example", "body": { "workspaceSlug": "example", "templateId": "example" } }, "effects": "May change state through PATCH /api/workspaces/{workspaceSlug}/project-templates/{templateId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/workspaces/*/project-templates/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "presets.create", "title": "Presets Create", "description": "Call POST /api/workspaces/{workspaceSlug}/presets.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/presets", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "workspaceSlug", "name" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Presets Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "workspaceSlug": "example", "name": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/presets", "body": { "workspaceSlug": "example", "name": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/presets. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/presets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "presets.update", "title": "Presets Update", "description": "Call PATCH /api/workspaces/{workspaceSlug}/presets/{presetId}.", "method": "PATCH", "path": "/api/workspaces/{workspaceSlug}/presets/{presetId}", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "workspaceSlug": { "type": "string", "minLength": 1 }, "presetId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "workspaceSlug", "presetId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Presets Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "workspaceSlug": "example", "presetId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/workspaces/example/presets/example", "body": { "workspaceSlug": "example", "presetId": "example" } }, "effects": "May change state through PATCH /api/workspaces/{workspaceSlug}/presets/{presetId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/workspaces/*/presets/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.compositions.create", "title": "Projects Compositions Create", "description": "Call POST /api/workspaces/{workspaceSlug}/projects/{projectId}/compositions.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/compositions", "permission": "assets:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "aspectRatio": { "type": "string", "enum": [ "portrait_9_16", "landscape_16_9" ] }, "snapshot": {}, "notes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "sourceKind": { "type": "string", "enum": [ "manual", "ai_generated", "imported" ] }, "generationStatus": { "type": "string", "enum": [ "pending", "queued", "running", "completed", "failed", "cancelled" ] } }, "required": [ "workspaceSlug", "projectId", "title", "aspectRatio", "snapshot" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Compositions Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example", "title": "example", "aspectRatio": "portrait_9_16", "snapshot": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/projects/example/compositions", "body": { "workspaceSlug": "example", "projectId": "example", "title": "example", "aspectRatio": "portrait_9_16", "snapshot": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/compositions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/projects/*/compositions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.compositions.update", "title": "Projects Compositions Update", "description": "Call PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/compositions/{compositionVersionId}.", "method": "PATCH", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/compositions/{compositionVersionId}", "permission": "assets:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "compositionVersionId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "maxLength": 255 }, "aspectRatio": { "type": "string", "enum": [ "portrait_9_16", "landscape_16_9" ] }, "snapshot": {}, "notes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "generationStatus": { "type": "string", "enum": [ "pending", "queued", "running", "completed", "failed", "cancelled" ] } }, "required": [ "workspaceSlug", "projectId", "compositionVersionId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Compositions Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example", "compositionVersionId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/workspaces/example/projects/example/compositions/example", "body": { "workspaceSlug": "example", "projectId": "example", "compositionVersionId": "example" } }, "effects": "May change state through PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/compositions/{compositionVersionId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/workspaces/*/projects/*/compositions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.render_jobs.create", "title": "Projects Render Jobs Create", "description": "Call POST /api/workspaces/{workspaceSlug}/projects/{projectId}/render-jobs.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/render-jobs", "permission": "exports:read", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "compositionVersionId": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1, "maxLength": 255 }, "outputFormat": { "type": "string", "enum": [ "mp4", "mov", "png_sequence", "gif" ] }, "priority": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Render Jobs Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/projects/example/render-jobs", "body": { "workspaceSlug": "example", "projectId": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/render-jobs. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/projects/*/render-jobs", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.render_jobs.update", "title": "Projects Render Jobs Update", "description": "Call PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/render-jobs/{renderJobId}.", "method": "PATCH", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/render-jobs/{renderJobId}", "permission": "exports:read", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "renderJobId": { "type": "string", "minLength": 1 }, "renderStatus": { "type": "string", "enum": [ "queued", "rendering", "completed", "failed", "cancelled" ] }, "failureReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outputAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "workspaceSlug", "projectId", "renderJobId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Render Jobs Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example", "renderJobId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/workspaces/example/projects/example/render-jobs/example", "body": { "workspaceSlug": "example", "projectId": "example", "renderJobId": "example" } }, "effects": "May change state through PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/render-jobs/{renderJobId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/workspaces/*/projects/*/render-jobs/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.scenes.regenerate", "title": "Projects Scenes Regenerate", "description": "Call POST /api/workspaces/{workspaceSlug}/projects/{projectId}/scenes/{sceneId}/generation/regenerate.", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/scenes/{sceneId}/generation/regenerate", "permission": "generation:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "sceneIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "provider": { "type": "string", "enum": [ "nexus-configured", "grok-imagine", "nano-banana", "cloudflare-media" ] }, "fallbackProvider": { "anyOf": [ { "type": "string", "enum": [ "nexus-configured", "grok-imagine", "nano-banana", "cloudflare-media" ] }, { "type": "null" } ] }, "candidateCount": { "type": "integer", "minimum": 1, "maximum": 4 }, "sourceAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outputKind": { "type": "string", "enum": [ "image", "video" ] }, "videoDurationSeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 15 }, { "type": "null" } ] }, "nexusProviderOverride": { "anyOf": [ { "type": "string", "enum": [ "openai", "google", "xai", "cloudflare" ] }, { "type": "null" } ] }, "nexusModelOverride": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "sceneId": { "type": "string", "minLength": 1 }, "assetId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "workspaceSlug", "projectId", "sceneId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Scenes Regenerate.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "runtime", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example", "sceneId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/projects/example/scenes/example/generation/regenerate", "body": { "workspaceSlug": "example", "projectId": "example", "sceneId": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/scenes/{sceneId}/generation/regenerate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/projects/*/scenes/*/generation/regenerate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.structured_brief.update", "title": "Projects Structured Brief Update", "description": "Call PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/structured-brief.", "method": "PATCH", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/structured-brief", "permission": "briefs:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "maxLength": 255 }, "objective": { "type": "string", "maxLength": 4000 }, "audience": { "type": "string", "maxLength": 4000 }, "keyMessage": { "type": "string", "maxLength": 4000 }, "channels": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "youtube", "linkedin", "x", "facebook" ] } }, "deliverables": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "constraints": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "referenceUrls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "successMetric": { "type": "string", "maxLength": 1000 }, "tonePillars": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "sourcePrompt": { "type": "string", "maxLength": 20000 }, "preferredDurationMs": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 180000 }, { "type": "null" } ] }, "styleNotes": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "captionMode": { "type": "string", "enum": [ "auto", "manual", "none" ] } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Structured Brief Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/workspaces/example/projects/example/structured-brief", "body": { "workspaceSlug": "example", "projectId": "example" } }, "effects": "May change state through PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/structured-brief. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/workspaces/*/projects/*/structured-brief", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.creative_plan.update", "title": "Projects Creative Plan Update", "description": "Call PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/creative-plan.", "method": "PATCH", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/creative-plan", "permission": "briefs:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube", "linkedin", "x", "facebook" ] }, "concept": { "type": "string", "maxLength": 4000 }, "hook": { "type": "string", "maxLength": 1000 }, "hookStrategy": { "type": "string", "maxLength": 4000 }, "callToAction": { "type": "string", "maxLength": 1000 }, "pacingStrategy": { "type": "string", "maxLength": 4000 }, "narrativeArc": { "type": "string", "maxLength": 4000 }, "narrativeStructure": { "type": "string", "maxLength": 4000 }, "visualDirection": { "type": "string", "maxLength": 4000 }, "shotStyle": { "type": "string", "maxLength": 4000 }, "providerStrategy": { "type": "object", "properties": { "imagePromptShape": { "type": "string", "minLength": 1, "maxLength": 4000 }, "motionPromptShape": { "type": "string", "minLength": 1, "maxLength": 4000 }, "renderTarget": { "type": "string", "minLength": 1, "maxLength": 4000 }, "shapingNotes": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "imagePromptShape", "motionPromptShape", "renderTarget", "shapingNotes" ], "additionalProperties": false }, "sceneOutline": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "sceneOrder": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 4000 }, "durationMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "sceneOrder", "title", "purpose", "durationMs" ], "additionalProperties": false } }, "distributionNotes": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Creative Plan Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/workspaces/example/projects/example/creative-plan", "body": { "workspaceSlug": "example", "projectId": "example" } }, "effects": "May change state through PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/creative-plan. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/workspaces/*/projects/*/creative-plan", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.scenes.update", "title": "Projects Scenes Update", "description": "Call PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/scenes/{sceneId}.", "method": "PATCH", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/scenes/{sceneId}", "permission": "briefs:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "sceneId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "maxLength": 255 }, "objective": { "type": "string", "maxLength": 4000 }, "visualPrompt": { "type": "string", "maxLength": 4000 }, "narration": { "type": "string", "maxLength": 4000 }, "durationMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "transitionLabel": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "motionRecommendation": { "type": "string", "maxLength": 4000 }, "transitionRecommendation": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "captionReference": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "workspaceSlug", "projectId", "sceneId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Scenes Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example", "sceneId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/workspaces/example/projects/example/scenes/example", "body": { "workspaceSlug": "example", "projectId": "example", "sceneId": "example" } }, "effects": "May change state through PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/scenes/{sceneId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/workspaces/*/projects/*/scenes/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "workspace:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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 workspace bootstrap", "description": "Get the signed workspace bootstrap payload for this service.", "method": "GET", "path": "/api/bootstrap", "permission": "workspace:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "identity.get", "title": "Get current identity", "description": "Get the authenticated Social Studio user and organization.", "method": "GET", "path": "/api/whoami", "permission": "workspace:read", "readOnly": true, "requiresConfirmation": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get current identity.", "additionalProperties": true }, "destructive": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/whoami", "body": null }, "effects": "Reads state through GET /api/whoami without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/whoami", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.list", "title": "List projects", "description": "List Social Studio projects.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/projects", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List projects.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/projects", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/projects without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/projects", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "planning.get", "title": "Get project planning", "description": "Get project planning data.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/planning", "permission": "briefs:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get project planning.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/projects/example/planning", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/projects/{projectId}/planning without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/projects/*/planning", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "generation.status", "title": "Get generation status", "description": "Get generation status for a project.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/generation/status", "permission": "assets:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get generation status.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/projects/example/generation/status", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/projects/{projectId}/generation/status without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/projects/*/generation/status", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "assets.list", "title": "List project assets", "description": "List assets generated for a project.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/assets", "permission": "assets:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "sceneId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List assets.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/projects/example/assets", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/projects/{projectId}/assets without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/projects/*/assets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "assets.upload", "title": "Upload project asset", "description": "Upload an image, video, audio file, or PDF into a Social Studio project.", "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "readOnly": false, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "method": "POST", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/assets/upload", "permission": "assets:write", "authorizationMode": "static", "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string", "minLength": 1, "maxLength": 35000000 }, "contentType": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "image/gif", "image/svg+xml", "video/mp4", "video/webm", "video/quicktime", "audio/mpeg", "audio/wav", "audio/mp4", "application/pdf" ] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "sceneId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "projectId", "contentBase64", "contentType", "fileName" ], "additionalProperties": false }, "agentContract": { "upload": { "profile": "inline-base64", "contentField": "contentBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 26214400, "acceptedContentTypes": [ "image/png", "image/jpeg", "image/webp", "image/gif", "image/svg+xml", "video/mp4", "video/webm", "video/quicktime", "audio/mpeg", "audio/wav", "audio/mp4", "application/pdf" ] } }, "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example", "contentBase64": "example", "contentType": "image/png", "fileName": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/workspaces/example/projects/example/assets/upload", "body": { "workspaceSlug": "example", "projectId": "example", "contentBase64": "example", "contentType": "image/png", "fileName": "example" } }, "effects": "May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/assets/upload. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/workspaces/*/projects/*/assets/upload", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operator.summary", "title": "Get operator summary", "description": "Get operator summary for a workspace.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/operator/summary", "permission": "settings:write", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get operator summary.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "runtime", "documentation": { "example_input": { "workspaceSlug": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/operator/summary", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/operator/summary without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/operator/summary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "billing.current_plan.get", "title": "Billing Current Plan Get", "description": "Call GET /api/workspaces/{workspaceSlug}/billing/current-plan.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/billing/current-plan", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Billing Current Plan Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/billing/current-plan", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/billing/current-plan without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/billing/current-plan", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "billing.usage_summary.get", "title": "Billing Usage Summary Get", "description": "Call GET /api/workspaces/{workspaceSlug}/billing/usage-summary.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/billing/usage-summary", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Billing Usage Summary Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/billing/usage-summary", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/billing/usage-summary without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/billing/usage-summary", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operator.audit_events.list", "title": "Operator Audit Events List", "description": "Call GET /api/workspaces/{workspaceSlug}/security/audit-events.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/security/audit-events", "permission": "settings:write", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Operator Audit Events List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/security/audit-events", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/security/audit-events without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/security/audit-events", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "assets.content.get", "title": "Assets Content Get", "description": "Call GET /api/workspaces/{workspaceSlug}/assets/{assetId}/content.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/assets/{assetId}/content", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "assetId": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "assetId", "token", "expiresAt" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Assets Content Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "public", "documentation": { "example_input": { "workspaceSlug": "example", "assetId": "example", "token": "example", "expiresAt": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/assets/example/content", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/assets/{assetId}/content without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/assets/*/content", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "assets.preview.get", "title": "Assets Preview Get", "description": "Call GET /api/workspaces/{workspaceSlug}/assets/{assetId}/preview.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/assets/{assetId}/preview", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "assetId": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "assetId", "token", "expiresAt" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Assets Preview Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "public", "documentation": { "example_input": { "workspaceSlug": "example", "assetId": "example", "token": "example", "expiresAt": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/assets/example/preview", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/assets/{assetId}/preview without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/assets/*/preview", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "generation.model_options.list", "title": "Generation Model Options List", "description": "Call GET /api/workspaces/{workspaceSlug}/generation/model-options.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/generation/model-options", "permission": "generation:write", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Generation Model Options List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/generation/model-options", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/generation/model-options without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/generation/model-options", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspace.creative_resources.list", "title": "Workspace Creative Resources List", "description": "Call GET /api/workspaces/{workspaceSlug}/creative-resources.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/creative-resources", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Workspace Creative Resources List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/creative-resources", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/creative-resources without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/creative-resources", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "settings.status.get", "title": "Settings Status Get", "description": "Call GET /api/workspaces/{workspaceSlug}/settings/status.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/settings/status", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Settings Status Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/settings/status", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/settings/status without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/settings/status", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "projects.sync.get", "title": "Projects Sync Get", "description": "Call GET /api/workspaces/{workspaceSlug}/projects/{projectId}/sync.", "method": "GET", "path": "/api/workspaces/{workspaceSlug}/projects/{projectId}/sync", "permission": "workspace:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Projects Sync Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "workspaceSlug": "example", "projectId": "example" }, "cli_example": [ "topolo actions --service topolo-social-studio --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/workspaces/example/projects/example/sync", "body": null }, "effects": "Reads state through GET /api/workspaces/{workspaceSlug}/projects/{projectId}/sync without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/workspaces/*/projects/*/sync", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 51, "matched_actions": 47, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 4, "configured_exclusions": 0, "configuration_findings": [], "notes": [] }, "runtime_contract_audit": { "status": "verified", "actions": 47, "contracts": 47, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/index.ts" ], "authorization_sources": [ "apps/api/src/index.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloSocialStudio/topolo.mobile-experience.json", "contract": { "version": "2026-07-03", "status": "approved", "mode": "native_capability", "appId": "app_topolo_social_studio", "localizationNamespace": "studio", "permissions": [ "workspace:read", "workspace:write", "social-studio:projects:read", "social-studio:projects:write" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/app/projects", "auth": { "audience": "topolo-social-studio", "scopes": [ "workspace:read", "workspace:write", "social-studio:projects:read", "social-studio:projects:write" ], "orgContext": "required" }, "routes": [ { "path": "/app/projects", "apiPath": "/api/workspaces/:workspaceSlug/projects", "title": "Projects", "titleKey": "studio.mobile.routes.projects.title", "template": "record.list", "dataSource": "studio.projects.list", "detailRoute": "/app/projects/:projectId/brief", "actions": [ { "id": "studio.projects.create", "title": "Create project", "titleKey": "studio.mobile.actions.projectsCreate.title", "type": "record.create", "permission": "social-studio:projects:write", "method": "POST", "path": "/api/workspaces/:workspaceSlug/projects", "fields": [ { "key": "title", "label": "Title", "type": "text", "required": true }, { "key": "objective", "label": "Objective", "type": "textarea" } ] } ] }, { "path": "/app/projects/:projectId/brief", "apiPath": "/api/workspaces/:workspaceSlug/projects/:projectId/planning", "title": "Project brief", "titleKey": "studio.mobile.routes.projectBrief.title", "template": "record.detail", "dataSource": "studio.projects.detail", "actions": [ { "id": "studio.brief.update", "title": "Update brief", "titleKey": "studio.mobile.actions.briefUpdate.title", "type": "record.update", "permission": "social-studio:projects:write", "method": "PATCH", "path": "/api/workspaces/:workspaceSlug/projects/:projectId/structured-brief", "fields": [ { "key": "title", "label": "Title", "type": "text" }, { "key": "objective", "label": "Objective", "type": "textarea" }, { "key": "audience", "label": "Audience", "type": "text" }, { "key": "styleNotes", "label": "Style notes", "type": "textarea" } ] }, { "id": "studio.planning.generate", "title": "Generate creative plan", "titleKey": "studio.mobile.actions.planningGenerate.title", "type": "record.create", "permission": "social-studio:projects:write", "method": "POST", "path": "/api/workspaces/:workspaceSlug/projects/:projectId/planning/generate" } ] }, { "path": "/app/projects/:projectId/review", "apiPath": "/api/workspaces/:workspaceSlug/projects/:projectId/sync", "title": "Review", "titleKey": "studio.mobile.routes.review.title", "template": "activity.timeline", "dataSource": "studio.projects.review" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "OPTIONS", "path": "*", "source_path": "apps/TopoloSocialStudio/apps/api/src/routes.ts" }, { "method": "ALL", "path": "/__seed/*", "source_path": "apps/TopoloSocialStudio/apps/api/src/routes.ts" }, { "method": "ALL", "path": "/healthz", "source_path": "apps/TopoloSocialStudio/apps/api/src/routes.ts" }, { "method": "ALL", "path": "/readyz", "source_path": "apps/TopoloSocialStudio/apps/api/src/routes.ts" }, { "method": "ALL", "path": "/api/bootstrap", "source_path": "apps/TopoloSocialStudio/apps/api/src/routes.ts" }, { "method": "GET", "path": "/api/organizations/data/export", "source_path": "apps/TopoloSocialStudio/apps/api/src/routes.ts" }, { "method": "DELETE", "path": "/api/organizations/data/erase", "source_path": "apps/TopoloSocialStudio/apps/api/src/routes.ts" }, { "method": "GET", "path": "/api/whoami", "source_path": "apps/TopoloSocialStudio/apps/api/src/routes.ts" }, { "method": "GET", "path": "/api/widget", "source_path": "apps/TopoloSocialStudio/apps/api/src/routes.ts" }, { "method": "DELETE", "path": "/api/workspaces/:workspaceSlug", "source_path": "apps/TopoloSocialStudio/apps/api/src/routes.ts" }, { "method": "LITERAL", "path": "/health", "source_path": "apps/TopoloSocialStudio/apps/jobs/src/index.ts" } ], "ui_routes": [], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "internal/apps/social-studio", "applications/social-studio" ], "present_paths": [ "internal/apps/social-studio", "applications/social-studio" ], "missing_paths": [], "human_reference": "/systems/topolo-social-studio", "machine_reference": "/machine/systems/topolo-social-studio.json", "action_examples": 47, "action_schemas": 47 }, "source_findings": [] }, "topolo-status": { "id": "topolo-status", "name": "Topolo Status", "slug": "topolo-status", "kind": "application", "visibility": "public", "repo_paths": [ "system-apps/TopoloStatus" ], "source_revisions": [ { "source_path": "system-apps/TopoloStatus", "repository": "system-apps/TopoloStatus", "revision": "7c200769ec189bf8efe4fe3c0030a7e72627ad81", "ref": "origin/staging" } ], "source_counts": { "source_files": 8, "test_files": 11, "test_cases": 0, "migration_files": 5, "database_tables": 0, "manifests": 1, "deploy_targets": 1, "actions": 9, "mobile_contracts": 1, "notifications": 8, "package_manifests": 1, "deployment_configs": 0 }, "manifests": [ { "source_path": "system-apps/TopoloStatus/topolo.app.json", "service_slug": "topolo-status", "name": "topolo-status", "app_id": "app_topolo_status", "compatibility_date": "2026-05-02", "primary_target": "api", "environments": [ "production", "staging" ], "targets": [ { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/worker.ts", "worker_name": "topolo-status", "subdomain": "status", "healthcheck_path": "/api/health", "variable_names": [ "AUTH_BASE_URL", "NOTIFICATION_ORGANIZATION_ID", "NOTIFICATION_WORKSPACE_ID", "STATUS_CATALOG_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "STATUS_DB", "target": null } ] } ], "notifications": [ "status.component.degraded", "status.component.recovered", "status.incident.created", "status.incident.resolved", "status.incident.updated", "status.maintenance.completed", "status.maintenance.scheduled", "status.maintenance.started" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_status", "events": [ { "type": "status.component.degraded", "version": 1, "description": "A persisted component crosses the sustained-failure threshold.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "component_host", "component_name", "http_status", "consecutive_fails", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "category": { "const": "status" }, "severity": { "const": "critical" }, "object_type": { "const": "status_component" }, "object_id": { "type": "string", "minLength": 1 }, "component_host": { "type": "string", "minLength": 1 }, "component_name": { "type": "string", "minLength": 1 }, "component_group": { "type": [ "string", "null" ] }, "http_status": { "type": "integer", "minimum": 0 }, "consecutive_fails": { "type": "integer", "minimum": 3 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Auth is degraded", "body": "Auth crossed the sustained-failure threshold.", "category": "status", "severity": "critical", "object_type": "status_component", "object_id": "auth.topolo.app", "component_host": "auth.topolo.app", "component_name": "Auth", "component_group": "platform", "http_status": 503, "consecutive_fails": 3, "occurred_at": "2026-07-21T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^status:component:" }, "sensitiveFields": [] }, { "type": "status.component.recovered", "version": 1, "description": "A persisted degraded component returns to operational status.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "component_host", "component_name", "http_status", "consecutive_fails", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "category": { "const": "status" }, "severity": { "const": "success" }, "object_type": { "const": "status_component" }, "object_id": { "type": "string", "minLength": 1 }, "component_host": { "type": "string", "minLength": 1 }, "component_name": { "type": "string", "minLength": 1 }, "component_group": { "type": [ "string", "null" ] }, "http_status": { "type": "integer", "minimum": 200, "maximum": 399 }, "consecutive_fails": { "const": 0 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Auth recovered", "body": "Auth returned to operational status.", "category": "status", "severity": "success", "object_type": "status_component", "object_id": "auth.topolo.app", "component_host": "auth.topolo.app", "component_name": "Auth", "component_group": "platform", "http_status": 200, "consecutive_fails": 0, "occurred_at": "2026-07-21T00:10:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^status:component:" }, "sensitiveFields": [] }, { "type": "status.incident.created", "version": 1, "description": "A durable status incident is created in the investigating state.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "incident_id", "incident_status", "revision", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "category": { "const": "status" }, "severity": { "enum": [ "minor", "major", "critical" ] }, "object_type": { "const": "status_incident" }, "object_id": { "type": "string", "minLength": 1 }, "incident_id": { "type": "string", "minLength": 1 }, "component_host": { "type": [ "string", "null" ] }, "component_name": { "type": [ "string", "null" ] }, "incident_status": { "const": "investigating" }, "revision": { "const": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Elevated Auth errors", "body": "We are investigating elevated authentication errors.", "category": "status", "severity": "major", "object_type": "status_incident", "object_id": "incident_123", "incident_id": "incident_123", "component_host": "auth.topolo.app", "component_name": "Auth", "incident_status": "investigating", "revision": 1, "occurred_at": "2026-07-21T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^status:incident:" }, "sensitiveFields": [] }, { "type": "status.incident.updated", "version": 1, "description": "A durable open status incident receives a new revision.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "incident_id", "incident_status", "revision", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "category": { "const": "status" }, "severity": { "enum": [ "minor", "major", "critical" ] }, "object_type": { "const": "status_incident" }, "object_id": { "type": "string", "minLength": 1 }, "incident_id": { "type": "string", "minLength": 1 }, "component_host": { "type": [ "string", "null" ] }, "component_name": { "type": [ "string", "null" ] }, "incident_status": { "enum": [ "investigating", "identified", "monitoring" ] }, "revision": { "type": "integer", "minimum": 2 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Elevated Auth errors", "body": "The cause is identified and mitigation is underway.", "category": "status", "severity": "major", "object_type": "status_incident", "object_id": "incident_123", "incident_id": "incident_123", "component_host": "auth.topolo.app", "component_name": "Auth", "incident_status": "identified", "revision": 2, "occurred_at": "2026-07-21T00:10:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^status:incident:" }, "sensitiveFields": [] }, { "type": "status.incident.resolved", "version": 1, "description": "A durable open status incident reaches the resolved state.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "incident_id", "incident_status", "revision", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "category": { "const": "status" }, "severity": { "const": "success" }, "object_type": { "const": "status_incident" }, "object_id": { "type": "string", "minLength": 1 }, "incident_id": { "type": "string", "minLength": 1 }, "component_host": { "type": [ "string", "null" ] }, "component_name": { "type": [ "string", "null" ] }, "incident_status": { "const": "resolved" }, "revision": { "type": "integer", "minimum": 2 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Elevated Auth errors", "body": "Authentication error rates have returned to normal.", "category": "status", "severity": "success", "object_type": "status_incident", "object_id": "incident_123", "incident_id": "incident_123", "component_host": "auth.topolo.app", "component_name": "Auth", "incident_status": "resolved", "revision": 3, "occurred_at": "2026-07-21T00:20:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^status:incident:" }, "sensitiveFields": [] }, { "type": "status.maintenance.scheduled", "version": 1, "description": "A durable platform maintenance window is scheduled.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "maintenance_id", "maintenance_status", "scheduled_start", "scheduled_end", "revision", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "category": { "const": "status" }, "severity": { "const": "info" }, "object_type": { "const": "status_maintenance" }, "object_id": { "type": "string", "minLength": 1 }, "maintenance_id": { "type": "string", "minLength": 1 }, "maintenance_status": { "const": "scheduled" }, "scheduled_start": { "type": "string", "format": "date-time" }, "scheduled_end": { "type": "string", "format": "date-time" }, "revision": { "const": 1 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Database maintenance", "body": "A short database maintenance window is scheduled.", "category": "status", "severity": "info", "object_type": "status_maintenance", "object_id": "maintenance_123", "maintenance_id": "maintenance_123", "maintenance_status": "scheduled", "scheduled_start": "2026-07-22T00:00:00.000Z", "scheduled_end": "2026-07-22T01:00:00.000Z", "revision": 1, "occurred_at": "2026-07-21T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^status:maintenance:" }, "sensitiveFields": [] }, { "type": "status.maintenance.started", "version": 1, "description": "A scheduled maintenance window enters the in-progress state.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "maintenance_id", "maintenance_status", "scheduled_start", "scheduled_end", "revision", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "category": { "const": "status" }, "severity": { "const": "warning" }, "object_type": { "const": "status_maintenance" }, "object_id": { "type": "string", "minLength": 1 }, "maintenance_id": { "type": "string", "minLength": 1 }, "maintenance_status": { "const": "in_progress" }, "scheduled_start": { "type": "string", "format": "date-time" }, "scheduled_end": { "type": "string", "format": "date-time" }, "revision": { "type": "integer", "minimum": 2 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Database maintenance", "body": "Database maintenance is now in progress.", "category": "status", "severity": "warning", "object_type": "status_maintenance", "object_id": "maintenance_123", "maintenance_id": "maintenance_123", "maintenance_status": "in_progress", "scheduled_start": "2026-07-22T00:00:00.000Z", "scheduled_end": "2026-07-22T01:00:00.000Z", "revision": 2, "occurred_at": "2026-07-22T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^status:maintenance:" }, "sensitiveFields": [] }, { "type": "status.maintenance.completed", "version": 1, "description": "An in-progress maintenance window reaches the completed state.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "maintenance_id", "maintenance_status", "scheduled_start", "scheduled_end", "revision", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "category": { "const": "status" }, "severity": { "const": "success" }, "object_type": { "const": "status_maintenance" }, "object_id": { "type": "string", "minLength": 1 }, "maintenance_id": { "type": "string", "minLength": 1 }, "maintenance_status": { "const": "completed" }, "scheduled_start": { "type": "string", "format": "date-time" }, "scheduled_end": { "type": "string", "format": "date-time" }, "revision": { "type": "integer", "minimum": 3 }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "Database maintenance", "body": "Database maintenance completed successfully.", "category": "status", "severity": "success", "object_type": "status_maintenance", "object_id": "maintenance_123", "maintenance_id": "maintenance_123", "maintenance_status": "completed", "scheduled_start": "2026-07-22T00:00:00.000Z", "scheduled_end": "2026-07-22T01:00:00.000Z", "revision": 3, "occurred_at": "2026-07-22T00:30:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^status:maintenance:" }, "sensitiveFields": [] } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "status:read", "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-status --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "declared_unserved", "route_key": "GET /api/widget", "evidence": "No matching served route was extracted from canonical staging source." } }, { "name": "status.get", "title": "Get status", "description": "Get platform status.", "method": "GET", "path": "/api/status", "authorizationMode": "public", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get status.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-status --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/status", "body": null }, "effects": "Reads state through GET /api/status without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "declared_unserved", "route_key": "GET /api/status", "evidence": "No matching served route was extracted from canonical staging source." } }, { "name": "status.poll", "title": "Run status poll", "description": "Poll all configured platform surfaces immediately.", "method": "POST", "path": "/poll", "permission": "status:poll", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Poll status.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-status --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/poll", "body": {} }, "effects": "May change state through POST /poll. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /poll", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "incidents.create", "title": "Create incident", "description": "Create a durable platform status incident.", "method": "POST", "path": "/api/incidents", "permission": "status:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "severity": { "type": "string", "enum": [ "minor", "major", "critical" ] }, "componentHost": { "type": "string", "minLength": 1 }, "componentName": { "type": "string", "minLength": 1 } }, "required": [ "title", "message", "severity" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "title": "example", "message": "example", "severity": "minor" }, "cli_example": [ "topolo actions --service topolo-status --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/incidents", "body": { "title": "example", "message": "example", "severity": "minor" } }, "effects": "May change state through POST /api/incidents. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/incidents", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "incidents.update", "title": "Update incident", "description": "Publish a durable update to an open status incident.", "method": "PATCH", "path": "/api/incidents/{incidentId}", "permission": "status:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "incidentId": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "severity": { "type": "string", "enum": [ "minor", "major", "critical" ] }, "status": { "type": "string", "enum": [ "investigating", "identified", "monitoring" ] } }, "required": [ "incidentId", "message" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "incidentId": "example", "message": "example" }, "cli_example": [ "topolo actions --service topolo-status --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/incidents/example", "body": { "incidentId": "example", "message": "example" } }, "effects": "May change state through PATCH /api/incidents/{incidentId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/incidents/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "incidents.resolve", "title": "Resolve incident", "description": "Resolve an open status incident with a final update.", "method": "POST", "path": "/api/incidents/{incidentId}/resolve", "permission": "status:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "incidentId": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": [ "incidentId", "message" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "incidentId": "example", "message": "example" }, "cli_example": [ "topolo actions --service topolo-status --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/incidents/example/resolve", "body": { "incidentId": "example", "message": "example" } }, "effects": "May change state through POST /api/incidents/{incidentId}/resolve. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/incidents/*/resolve", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "maintenance.schedule", "title": "Schedule maintenance", "description": "Create a durable scheduled maintenance window.", "method": "POST", "path": "/api/maintenance", "permission": "status:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "scheduledStart": { "type": "string", "minLength": 1 }, "scheduledEnd": { "type": "string", "minLength": 1 } }, "required": [ "title", "message", "scheduledStart", "scheduledEnd" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "title": "example", "message": "example", "scheduledStart": "example", "scheduledEnd": "example" }, "cli_example": [ "topolo actions --service topolo-status --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/maintenance", "body": { "title": "example", "message": "example", "scheduledStart": "example", "scheduledEnd": "example" } }, "effects": "May change state through POST /api/maintenance. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/maintenance", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "maintenance.start", "title": "Start maintenance", "description": "Move a scheduled maintenance window into progress.", "method": "POST", "path": "/api/maintenance/{maintenanceId}/start", "permission": "status:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "maintenanceId": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": [ "maintenanceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "maintenanceId": "example" }, "cli_example": [ "topolo actions --service topolo-status --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/maintenance/example/start", "body": { "maintenanceId": "example" } }, "effects": "May change state through POST /api/maintenance/{maintenanceId}/start. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/maintenance/*/start", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "maintenance.complete", "title": "Complete maintenance", "description": "Complete an in-progress maintenance window.", "method": "POST", "path": "/api/maintenance/{maintenanceId}/complete", "permission": "status:write", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "maintenanceId": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": [ "maintenanceId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "maintenanceId": "example" }, "cli_example": [ "topolo actions --service topolo-status --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/maintenance/example/complete", "body": { "maintenanceId": "example" } }, "effects": "May change state through POST /api/maintenance/{maintenanceId}/complete. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/maintenance/*/complete", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 7, "matched_actions": 7, "declared_unserved_actions": [ "GET /api/status", "GET /api/widget" ], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 0, "configured_exclusions": 2, "configuration_findings": [ "* /: exclusion matches no served route", "* /status: exclusion matches no served route" ], "notes": [] }, "runtime_contract_audit": { "status": "verified", "actions": 9, "contracts": 9, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/worker.ts" ], "authorization_sources": [ "apps/api/src/worker.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "system-apps/TopoloStatus/topolo.mobile-experience.json", "contract": { "version": "2026-06-29", "status": "approved", "mode": "native_capability", "appId": "app_topolo_status", "localizationNamespace": "status", "permissions": [ "status:read" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/services", "auth": { "audience": "topolo-status", "scopes": [ "status:read" ] }, "routes": [ { "path": "/services", "apiPath": "/api/status", "title": "Services", "titleKey": "status.mobile.routes.services.title", "template": "record.list", "dataSource": "status.services.list" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "LITERAL", "path": "/api/incidents", "source_path": "system-apps/TopoloStatus/apps/api/src/status-lifecycle.ts" }, { "method": "LITERAL", "path": "/api/maintenance", "source_path": "system-apps/TopoloStatus/apps/api/src/status-lifecycle.ts" }, { "method": "ALL", "path": "*", "source_path": "system-apps/TopoloStatus/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/poll", "source_path": "system-apps/TopoloStatus/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/health", "source_path": "system-apps/TopoloStatus/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/widget", "source_path": "system-apps/TopoloStatus/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/api/status", "source_path": "system-apps/TopoloStatus/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/", "source_path": "system-apps/TopoloStatus/apps/api/src/worker.ts" }, { "method": "LITERAL", "path": "/status", "source_path": "system-apps/TopoloStatus/apps/api/src/worker.ts" } ], "ui_routes": [], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/status", "internal/apps/status" ], "present_paths": [ "applications/status", "internal/apps/status" ], "missing_paths": [], "human_reference": "/systems/topolo-status", "machine_reference": "/machine/systems/topolo-status.json", "action_examples": 9, "action_schemas": 9 }, "source_findings": [ { "type": "declared_unserved_actions", "source_path": "system-apps/TopoloStatus/topolo.app.json", "detail": [ "GET /api/status", "GET /api/widget" ] }, { "type": "action_coverage_configuration", "source_path": "system-apps/TopoloStatus/topolo.app.json", "detail": [ "* /: exclusion matches no served route", "* /status: exclusion matches no served route" ] } ] }, "topolo-support": { "id": "topolo-support", "name": "Topolo Support", "slug": "topolo-support", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloSupport" ], "source_revisions": [ { "source_path": "apps/TopoloSupport", "repository": "apps/TopoloSupport", "revision": "77105cf20c40ad714d45907641b33ea6a6dbdd04", "ref": "origin/staging" } ], "source_counts": { "source_files": 91, "test_files": 56, "test_cases": 0, "migration_files": 14, "database_tables": 0, "manifests": 1, "deploy_targets": 2, "actions": 26, "mobile_contracts": 1, "notifications": 9, "package_manifests": 1, "deployment_configs": 0 }, "manifests": [ { "source_path": "apps/TopoloSupport/topolo.app.json", "service_slug": "topolo-support", "name": "topolo-support", "app_id": "app_topolo_support", "compatibility_date": "2026-04-10", "primary_target": "web", "environments": [ "development", "production", "staging" ], "targets": [ { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/worker.ts", "worker_name": "topolo-support-api", "subdomain": null, "healthcheck_path": "/api/health", "variable_names": [ "AUTH_API_URL", "ENVIRONMENT", "NEXUS_GATEWAY_URL", "SUPPORT_PUBLIC_BASE_URL", "TOPOLO_NEXUS_API_URL", "TOPOLO_NOTIFY_URL", "TOPOLO_SEED_APP_ID" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "SUPPORT_CORE_DB", "target": null }, { "kind": "d1", "binding": "SUPPORT_DB", "target": null }, { "kind": "d1", "binding": "SUPPORT_INGEST_DB", "target": null }, { "kind": "d1", "binding": "SUPPORT_OUTBOX_DB", "target": null }, { "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 } ] }, { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-support", "subdomain": null, "healthcheck_path": "/api/health", "variable_names": [ "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null }, { "kind": "services", "binding": "API", "target": null } ] } ], "notifications": [ "support.customer_reply.received", "support.notification.delivery_failed", "support.sla.breached", "support.sla.warning", "support.ticket.assigned", "support.ticket.created", "support.ticket.escalated", "support.ticket.reopened", "support.ticket.resolved" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_support", "events": [ { "type": "support.customer_reply.received", "version": 1, "description": "Support recorded the durable customer reply received transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "recipient_email": { "type": "string", "format": "email" }, "category": { "type": "string" }, "severity": { "enum": [ "info", "success", "warning", "critical" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "title": "Requester replied: Login issue", "body": "The requester added a public reply.", "recipient_email": "agent@example.com", "object_id": "ticket_123", "occurred_at": "2026-07-17T12:00:00.000Z" } ], "dataClassification": "confidential", "sensitiveFields": [ "recipient_email", "body" ], "recipients": { "modes": [ "organization_member", "external" ], "externalAddress": "optional" }, "idempotency": { "required": true, "pattern": "^support:outbox:" } }, { "type": "support.notification.delivery_failed", "version": 1, "description": "A persisted Support outbox delivery exhausted its retry budget.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "ticket_id", "ticket_subject", "surface", "priority", "severity", "category", "object_type", "object_id", "cta_url", "cta_label", "occurred_at", "failure_reason", "delivery_id" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "ticket_id": { "type": "string", "minLength": 1 }, "ticket_subject": { "type": "string", "minLength": 1 }, "surface": { "const": "action" }, "priority": { "const": "high" }, "severity": { "const": "warning" }, "category": { "const": "support" }, "object_type": { "const": "support_notification" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "failure_reason": { "type": "string", "minLength": 1 }, "delivery_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "examples": [ { "title": "Support notification failed: Login issue", "body": "A ticket notification exhausted its delivery retries.", "ticket_id": "ticket_123", "ticket_subject": "Login issue", "surface": "action", "priority": "high", "severity": "warning", "category": "support", "object_type": "support_notification", "object_id": "delivery_123", "cta_url": "https://support.topolo.app/tickets/ticket_123", "cta_label": "Open ticket", "occurred_at": "2026-07-20T12:00:00.000Z", "failure_reason": "retry limit reached", "delivery_id": "delivery_123" } ], "dataClassification": "confidential", "sensitiveFields": [ "body", "ticket_subject", "failure_reason" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^support:delivery:" } }, { "type": "support.sla.breached", "version": 1, "description": "A persisted unresolved Support ticket crossed its priority-based SLA deadline.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "ticket_id", "ticket_subject", "surface", "priority", "severity", "category", "object_type", "object_id", "cta_url", "cta_label", "occurred_at", "metric", "due_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "ticket_id": { "type": "string", "minLength": 1 }, "ticket_subject": { "type": "string", "minLength": 1 }, "surface": { "const": "action" }, "priority": { "const": "urgent" }, "severity": { "const": "critical" }, "category": { "const": "support" }, "object_type": { "const": "support_sla" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "metric": { "enum": [ "first_response", "resolution" ] }, "due_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "SLA breached: Login issue", "body": "First response is breached.", "ticket_id": "ticket_123", "ticket_subject": "Login issue", "surface": "action", "priority": "urgent", "severity": "critical", "category": "support", "object_type": "support_sla", "object_id": "ticket_123:first_response:2026-07-20T12:00:00.000Z", "cta_url": "https://support.topolo.app/tickets/ticket_123", "cta_label": "Open ticket", "occurred_at": "2026-07-20T12:01:00.000Z", "metric": "first_response", "due_at": "2026-07-20T12:00:00.000Z" } ], "dataClassification": "confidential", "sensitiveFields": [ "body", "ticket_subject" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^support:sla:" } }, { "type": "support.sla.warning", "version": 1, "description": "A persisted unresolved Support ticket entered its SLA warning window.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "ticket_id", "ticket_subject", "surface", "priority", "severity", "category", "object_type", "object_id", "cta_url", "cta_label", "occurred_at", "metric", "due_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "ticket_id": { "type": "string", "minLength": 1 }, "ticket_subject": { "type": "string", "minLength": 1 }, "surface": { "const": "action" }, "priority": { "const": "high" }, "severity": { "const": "warning" }, "category": { "const": "support" }, "object_type": { "const": "support_sla" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "metric": { "enum": [ "first_response", "resolution" ] }, "due_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "examples": [ { "title": "SLA warning: Login issue", "body": "Resolution is warning.", "ticket_id": "ticket_123", "ticket_subject": "Login issue", "surface": "action", "priority": "high", "severity": "warning", "category": "support", "object_type": "support_sla", "object_id": "ticket_123:resolution:2026-07-20T16:00:00.000Z", "cta_url": "https://support.topolo.app/tickets/ticket_123", "cta_label": "Open ticket", "occurred_at": "2026-07-20T12:00:00.000Z", "metric": "resolution", "due_at": "2026-07-20T16:00:00.000Z" } ], "dataClassification": "confidential", "sensitiveFields": [ "body", "ticket_subject" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^support:sla:" } }, { "type": "support.ticket.assigned", "version": 1, "description": "A support ticket was assigned to an organization member.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "surface": { "enum": [ "notification", "action" ] }, "action_kind": { "enum": [ "open", "review", "approve", "resolve", "complete" ] }, "action_status": { "type": "string" }, "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" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" }, "actor_display_name": { "type": "string" }, "recipient_email": { "type": "string", "format": "email" }, "thread_key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "action_context": { "type": "object" } }, "additionalProperties": true }, "examples": [ { "title": "A support ticket was assigned to an organization member.", "body": "Open the owning app to review this event.", "object_id": "object_123", "occurred_at": "2026-07-17T00:00:00.000Z" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member", "external" ], "externalAddress": "optional" }, "idempotency": { "required": true, "pattern": "^support:ticket-assigned:" }, "sensitiveFields": [ "recipient_email", "body" ] }, { "type": "support.ticket.created", "version": 1, "description": "Support recorded the durable ticket created transition.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "recipient_email": { "type": "string", "format": "email" }, "category": { "type": "string" }, "severity": { "enum": [ "info", "success", "warning", "critical" ] }, "object_type": { "type": "string" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string" } }, "additionalProperties": true }, "examples": [ { "title": "Ticket received: Login issue", "body": "We received your support request.", "recipient_email": "requester@example.com", "object_id": "ticket_123", "occurred_at": "2026-07-17T12:00:00.000Z" } ], "dataClassification": "confidential", "sensitiveFields": [ "recipient_email", "body" ], "recipients": { "modes": [ "organization_member", "external" ], "externalAddress": "optional" }, "idempotency": { "required": true, "pattern": "^support:outbox:" } }, { "type": "support.ticket.escalated", "version": 1, "description": "A persisted Support workflow event moved a ticket to urgent priority.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "ticket_id", "ticket_subject", "surface", "priority", "severity", "category", "object_type", "object_id", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "ticket_id": { "type": "string", "minLength": 1 }, "ticket_subject": { "type": "string", "minLength": 1 }, "surface": { "const": "action" }, "priority": { "const": "urgent" }, "severity": { "const": "critical" }, "category": { "const": "support" }, "object_type": { "const": "ticket" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "examples": [ { "title": "Urgent ticket: Login issue", "body": "This ticket was escalated to urgent priority.", "ticket_id": "ticket_123", "ticket_subject": "Login issue", "surface": "action", "priority": "urgent", "severity": "critical", "category": "support", "object_type": "ticket", "object_id": "ticket_123", "cta_url": "https://support.topolo.app/tickets/ticket_123", "cta_label": "Open ticket", "occurred_at": "2026-07-20T12:00:00.000Z", "actor_id": "user_123" } ], "dataClassification": "confidential", "sensitiveFields": [ "body", "ticket_subject" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^support:ticket-event:" } }, { "type": "support.ticket.reopened", "version": 1, "description": "A persisted Support workflow event reopened a resolved or closed ticket.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "ticket_id", "ticket_subject", "surface", "priority", "severity", "category", "object_type", "object_id", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "ticket_id": { "type": "string", "minLength": 1 }, "ticket_subject": { "type": "string", "minLength": 1 }, "surface": { "const": "action" }, "priority": { "enum": [ "high", "urgent" ] }, "severity": { "const": "warning" }, "category": { "const": "support" }, "object_type": { "const": "ticket" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "examples": [ { "title": "Ticket reopened: Login issue", "body": "A resolved ticket was reopened and needs attention.", "ticket_id": "ticket_123", "ticket_subject": "Login issue", "surface": "action", "priority": "high", "severity": "warning", "category": "support", "object_type": "ticket", "object_id": "ticket_123", "cta_url": "https://support.topolo.app/tickets/ticket_123", "cta_label": "Open ticket", "occurred_at": "2026-07-20T12:00:00.000Z", "actor_id": "user_123" } ], "dataClassification": "confidential", "sensitiveFields": [ "body", "ticket_subject" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^support:ticket-event:" } }, { "type": "support.ticket.resolved", "version": 1, "description": "A persisted Support workflow event marked a ticket resolved.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "ticket_id", "ticket_subject", "surface", "priority", "severity", "category", "object_type", "object_id", "cta_url", "cta_label", "occurred_at" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "ticket_id": { "type": "string", "minLength": 1 }, "ticket_subject": { "type": "string", "minLength": 1 }, "surface": { "const": "notification" }, "priority": { "const": "normal" }, "severity": { "const": "success" }, "category": { "const": "support" }, "object_type": { "const": "ticket" }, "object_id": { "type": "string", "minLength": 1 }, "cta_url": { "type": "string", "format": "uri" }, "cta_label": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "examples": [ { "title": "Ticket resolved: Login issue", "body": "This ticket was marked resolved.", "ticket_id": "ticket_123", "ticket_subject": "Login issue", "surface": "notification", "priority": "normal", "severity": "success", "category": "support", "object_type": "ticket", "object_id": "ticket_123", "cta_url": "https://support.topolo.app/tickets/ticket_123", "cta_label": "Open ticket", "occurred_at": "2026-07-20T12:00:00.000Z", "actor_id": "user_123" } ], "dataClassification": "confidential", "sensitiveFields": [ "body", "ticket_subject" ], "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^support:ticket-event:" } } ] }, "actions": [ { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "tickets: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-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "declared_unserved", "route_key": "GET /api/widget", "evidence": "No matching served route was extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "Delete support workspace", "description": "Delete an empty non-default support workspace.", "method": "DELETE", "path": "/api/support/workspace/{workspaceId}", "permission": "workspace:delete", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/support/workspace/example", "body": null }, "effects": "May change state through DELETE /api/support/workspace/{workspaceId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/support/workspace/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "inboxes.create", "title": "Create support inbox", "description": "Create an inbox in a support workspace.", "method": "POST", "path": "/api/support/workspace/{workspaceId}/inboxes", "permission": "tickets:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 2 }, "slug": { "type": "string", "minLength": 1 }, "channel": { "type": "string", "enum": [ "portal", "api", "email", "webhook", "widget", "messaging", "manual" ] }, "isDefault": { "type": "boolean" } }, "required": [ "workspaceId", "name" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example", "name": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/support/workspace/example/inboxes", "body": { "workspaceId": "example", "name": "example" } }, "effects": "May change state through POST /api/support/workspace/{workspaceId}/inboxes. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/support/workspace/*/inboxes", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "inboxes.update", "title": "Update support inbox", "description": "Update an inbox in a support workspace.", "method": "PATCH", "path": "/api/support/workspace/{workspaceId}/inboxes/{inboxId}", "permission": "tickets:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "inboxId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 2 }, "slug": { "type": "string", "minLength": 1 }, "channel": { "type": "string", "enum": [ "portal", "api", "email", "webhook", "widget", "messaging", "manual" ] }, "isDefault": { "type": "boolean" }, "isActive": { "type": "boolean" } }, "required": [ "workspaceId", "inboxId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example", "inboxId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/support/workspace/example/inboxes/example", "body": { "workspaceId": "example", "inboxId": "example" } }, "effects": "May change state through PATCH /api/support/workspace/{workspaceId}/inboxes/{inboxId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/support/workspace/*/inboxes/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "tickets.list", "title": "List tickets", "description": "List support tickets.", "method": "GET", "path": "/api/support/tickets", "permission": "tickets:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List tickets.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/support/tickets", "body": null }, "effects": "Reads state through GET /api/support/tickets without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/support/tickets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "tickets.create", "title": "Create ticket", "description": "Create a support ticket.", "method": "POST", "path": "/api/support/tickets", "permission": "tickets:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "inboxId": { "type": "string", "minLength": 1 }, "subject": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "serviceName": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "priority": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "requesterName": { "type": "string", "minLength": 1 }, "requesterEmail": { "type": "string", "minLength": 1 }, "requesterUserId": { "type": "string", "minLength": 1 }, "requesterOrgId": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "sourceReference": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create ticket.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example", "inboxId": "example", "subject": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/support/tickets", "body": { "workspaceId": "example", "inboxId": "example", "subject": "example" } }, "effects": "May change state through POST /api/support/tickets. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/support/tickets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "tickets.get", "title": "Get ticket", "description": "Get one support ticket.", "method": "GET", "path": "/api/support/tickets/{ticketId}", "permission": "tickets:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "ticketId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get ticket.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "ticketId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/support/tickets/example", "body": null }, "effects": "Reads state through GET /api/support/tickets/{ticketId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/support/tickets/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "tickets.update", "title": "Update ticket", "description": "Update one support ticket.", "method": "PATCH", "path": "/api/support/tickets/{ticketId}", "permission": "tickets:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "priority": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "assignedToUserId": { "type": "string", "minLength": 1 }, "assignedToName": { "type": "string", "minLength": 1 }, "assignedToEmail": { "type": "string", "minLength": 1 } }, "required": [ "ticketId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update ticket.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "ticketId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/support/tickets/example", "body": { "ticketId": "example" } }, "effects": "May change state through PATCH /api/support/tickets/{ticketId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/support/tickets/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ticket_messages.create", "title": "Create ticket message", "description": "Add a message to a support ticket.", "method": "POST", "path": "/api/support/tickets/{ticketId}/messages", "permission": "tickets:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "visibility": { "type": "string", "minLength": 1 }, "channel": { "type": "string", "minLength": 1 }, "sourceReference": { "type": "string", "minLength": 1 }, "macroId": { "type": "string", "minLength": 1 } }, "required": [ "ticketId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create ticket message.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "ticketId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/support/tickets/example/messages", "body": { "ticketId": "example" } }, "effects": "May change state through POST /api/support/tickets/{ticketId}/messages. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/support/tickets/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "macros.list", "title": "List macros", "description": "List support macros.", "method": "GET", "path": "/api/support/macros", "permission": "macros:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by List macros.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/support/macros", "body": null }, "effects": "Reads state through GET /api/support/macros without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/support/macros", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "macros.get", "title": "Get macro", "description": "Get one support macro.", "method": "GET", "path": "/api/support/macros/{macroId}", "permission": "macros:read", "authorizationMode": "static", "readOnly": true, "inputSchema": { "type": "object", "properties": { "macroId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "macroId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "macroId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/support/macros/example", "body": null }, "effects": "Reads state through GET /api/support/macros/{macroId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/support/macros/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "macros.create", "title": "Create macro", "description": "Create a support macro.", "method": "POST", "path": "/api/support/macros", "permission": "macros:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "visibility": { "type": "string", "minLength": 1 }, "suggestedStatus": { "type": "string", "minLength": 1 }, "suggestedPriority": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create macro.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example", "title": "example", "body": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/support/macros", "body": { "workspaceId": "example", "title": "example", "body": "example" } }, "effects": "May change state through POST /api/support/macros. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/support/macros", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operations.get", "title": "Get operations overview", "description": "Get support routing, triage, agent capacity, and queue analytics.", "method": "GET", "path": "/api/support/operations", "permission": "tickets:write", "authorizationMode": "static", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Get operations overview.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/support/operations", "body": null }, "effects": "Reads state through GET /api/support/operations without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/support/operations", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operations.section.get", "title": "Get operations section", "description": "Get one support operations section.", "method": "GET", "path": "/api/support/operations/{section}", "permission": "tickets:write", "authorizationMode": "static", "readOnly": true, "inputSchema": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "overview", "workspaces", "settings", "agents", "routing", "channels", "intelligence" ] }, "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "section" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "documentation": { "example_input": { "section": "overview" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/support/operations/overview", "body": null }, "effects": "Reads state through GET /api/support/operations/{section} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/support/operations/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operations.settings.update", "title": "Update operations settings", "description": "Update support workspace assignment, triage, CSAT, timezone, and business-hour settings.", "method": "PATCH", "path": "/api/support/operations/settings", "permission": "tickets:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 }, "businessHours": { "type": "string" }, "autoAssignmentEnabled": { "type": "boolean" }, "aiTriageEnabled": { "type": "boolean" }, "csatEnabled": { "type": "boolean" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update operations settings.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example", "timezone": "example", "businessHours": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/support/operations/settings", "body": { "workspaceId": "example", "timezone": "example", "businessHours": "example" } }, "effects": "May change state through PATCH /api/support/operations/settings. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/support/operations/settings", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operations.agents.update", "title": "Update support agent profile", "description": "Update a support agent status, capacity, skills, or active state.", "method": "PATCH", "path": "/api/support/operations/agents/{agentId}", "permission": "tickets:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "maxCapacity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "skills": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "isActive": { "type": "boolean" } }, "required": [ "agentId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update support agent profile.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "agentId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/support/operations/agents/example", "body": { "agentId": "example" } }, "effects": "May change state through PATCH /api/support/operations/agents/{agentId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/support/operations/agents/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operations.routing_rules.create", "title": "Create routing rule", "description": "Create a support routing rule for ticket assignment.", "method": "POST", "path": "/api/support/operations/routing-rules", "permission": "tickets:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "priorityOrder": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "matchSource": { "type": "string" }, "matchCategory": { "type": "string" }, "matchPriority": { "type": "string" }, "targetInboxId": { "type": "string" }, "requiredSkills": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "isActive": { "type": "boolean" } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Create routing rule.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example", "name": "example", "priorityOrder": 1 }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/support/operations/routing-rules", "body": { "workspaceId": "example", "name": "example", "priorityOrder": 1 } }, "effects": "May change state through POST /api/support/operations/routing-rules. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/support/operations/routing-rules", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operations.routing_rules.update", "title": "Update routing rule", "description": "Update a support routing rule for ticket assignment.", "method": "PATCH", "path": "/api/support/operations/routing-rules/{ruleId}", "permission": "tickets:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ruleId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "priorityOrder": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "matchSource": { "type": "string" }, "matchCategory": { "type": "string" }, "matchPriority": { "type": "string" }, "targetInboxId": { "type": "string" }, "requiredSkills": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "isActive": { "type": "boolean" } }, "required": [ "ruleId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Update routing rule.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "ruleId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PATCH", "path": "/api/support/operations/routing-rules/example", "body": { "ruleId": "example" } }, "effects": "May change state through PATCH /api/support/operations/routing-rules/{ruleId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PATCH /api/support/operations/routing-rules/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operations.channel_connections.create", "title": "Connect support mailbox channel", "description": "Connect an IMAP mailbox to a support inbox through Nexus-managed mailbox credentials.", "method": "POST", "path": "/api/support/operations/channel-connections", "permission": "tickets:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "inboxId": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "displayName": { "type": "string" }, "authUsername": { "type": "string", "minLength": 1 }, "authPassword": { "type": "string", "minLength": 1 }, "imapHost": { "type": "string", "minLength": 1 }, "imapPort": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "imapSecure": { "type": "boolean" }, "smtpHost": { "type": "string", "minLength": 1 }, "smtpPort": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "smtpSecure": { "type": "boolean" } }, "required": [ "inboxId", "authUsername", "authPassword", "imapHost", "smtpHost" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Connect support mailbox channel.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "inboxId": "example", "authUsername": "example", "authPassword": "example", "imapHost": "example", "smtpHost": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/support/operations/channel-connections", "body": { "inboxId": "example", "authUsername": "example", "authPassword": "example", "imapHost": "example", "smtpHost": "example" } }, "effects": "May change state through POST /api/support/operations/channel-connections. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/support/operations/channel-connections", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operations.channel_connections.sync", "title": "Sync support mailbox channel", "description": "Fetch new IMAP messages from a connected support mailbox channel.", "method": "POST", "path": "/api/support/operations/channel-connections/{connectionId}/sync", "permission": "tickets:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "connectionId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "connectionId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sync support mailbox channel.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "connectionId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/support/operations/channel-connections/example/sync", "body": { "connectionId": "example" } }, "effects": "May change state through POST /api/support/operations/channel-connections/{connectionId}/sync. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/support/operations/channel-connections/*/sync", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operations.triage", "title": "Refresh triage intelligence", "description": "Refresh deterministic triage summaries, intents, sentiment, and automation scores for open tickets.", "method": "POST", "path": "/api/support/operations/triage", "permission": "tickets:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Refresh triage intelligence.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/support/operations/triage", "body": { "workspaceId": "example" } }, "effects": "May change state through POST /api/support/operations/triage. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/support/operations/triage", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "operations.route", "title": "Run routing assignment", "description": "Assign open support tickets to active agents using workspace routing rules and capacity.", "method": "POST", "path": "/api/support/operations/route", "permission": "tickets:write", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Run routing assignment.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/support/operations/route", "body": { "workspaceId": "example" } }, "effects": "May change state through POST /api/support/operations/route. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/support/operations/route", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "ticket_notifications.dispatch", "title": "Dispatch ticket notification", "description": "Dispatch notifications for a support ticket.", "method": "POST", "path": "/api/support/tickets/{ticketId}/notifications/dispatch", "permission": "replies:invoke", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string", "minLength": 1 } }, "required": [ "ticketId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Dispatch ticket notification.", "additionalProperties": true }, "destructive": false, "agentAccess": "confirm", "documentation": { "example_input": { "ticketId": "example" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/support/tickets/example/notifications/dispatch", "body": { "ticketId": "example" } }, "effects": "May change state through POST /api/support/tickets/{ticketId}/notifications/dispatch. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/support/tickets/*/notifications/dispatch", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.export", "title": "Export support organization data", "description": "Export the authenticated organization's portable Support data with secrets and operational errors redacted.", "method": "GET", "path": "/api/support/privacy", "permission": "privacy:read", "authorizationMode": "static", "readOnly": true, "requiresConfirmation": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/support/privacy", "body": null }, "effects": "Reads state through GET /api/support/privacy without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/support/privacy", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.erase", "title": "Erase support organization data", "description": "Permanently erase the authenticated organization's Support data and retain only a hash-based erasure receipt.", "method": "DELETE", "path": "/api/support/privacy", "permission": "privacy:delete", "authorizationMode": "static", "readOnly": false, "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": true, "agentAccess": "confirm", "documentation": { "example_input": { "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/support/privacy", "body": null }, "effects": "May change state through DELETE /api/support/privacy. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/support/privacy", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "privacy.protection_canary", "title": "Check support content protection", "description": "Verify ticket content, requester and assignee PII, message and notification bodies, webhook payloads, and sensitive source references use readable canonical protection envelopes with valid keyed lookup digests.", "method": "GET", "path": "/api/support/privacy/protection/canary", "permission": "privacy:read", "authorizationMode": "static", "readOnly": true, "requiresConfirmation": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "additionalProperties": true }, "destructive": false, "agentAccess": "auto", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-support --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/support/privacy/protection/canary", "body": null }, "effects": "Reads state through GET /api/support/privacy/protection/canary without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/support/privacy/protection/canary", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 31, "matched_actions": 25, "declared_unserved_actions": [ "GET /api/widget" ], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 6, "configured_exclusions": 8, "configuration_findings": [ "* /api/auth/*: exclusion matches no served route", "* /api/support/*: exclusion matches no served route" ], "notes": [ "no routes extracted from api", "31 manually-declared route(s)" ] }, "runtime_contract_audit": { "status": "verified", "actions": 26, "contracts": 26, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/worker.ts" ], "authorization_sources": [ "apps/api/src/worker.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloSupport/topolo.mobile-experience.json", "contract": { "version": "2026-06-29", "status": "approved", "mode": "native_capability", "appId": "app_topolo_support", "localizationNamespace": "support", "permissions": [ "tickets:read", "tickets:write", "macros:read", "macros:write" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/tickets", "auth": { "audience": "topolo-support", "scopes": [ "tickets:read", "tickets:write", "macros:read", "macros:write" ] }, "routes": [ { "path": "/tickets", "apiPath": "/api/support/tickets", "title": "Tickets", "titleKey": "support.mobile.routes.tickets.title", "template": "record.list", "dataSource": "support.tickets.list", "detailRoute": "/tickets/:id", "actions": [ { "id": "support.tickets.create", "title": "Create ticket", "type": "record.create", "permission": "tickets:write", "method": "POST", "path": "/api/support/tickets", "fields": [ { "key": "subject", "label": "Subject", "labelKey": "support.supportshared.subject", "type": "text", "required": true }, { "key": "description", "label": "Description", "labelKey": "support.supportshared.description", "type": "textarea", "required": true }, { "key": "serviceName", "label": "Service", "labelKey": "support.supportshared.service", "type": "text", "required": true }, { "key": "priority", "label": "Priority", "labelKey": "support.supportshared.priority", "type": "text", "required": true }, { "key": "category", "label": "Category", "labelKey": "support.supportshared.category", "type": "text", "required": true }, { "key": "requesterName", "label": "Requester name", "type": "text" }, { "key": "requesterEmail", "label": "Requester email", "type": "email" }, { "key": "status", "label": "Status", "labelKey": "support.supportshared.status", "type": "text" }, { "key": "assignedToName", "label": "Assignee name", "type": "text" }, { "key": "assignedToEmail", "label": "Assignee email", "type": "email" } ], "titleKey": "support.mobile.actions.tickets.create.title" }, { "id": "support.tickets.update", "title": "Update ticket", "type": "record.update", "permission": "tickets:write", "method": "PATCH", "path": "/api/support/tickets/:id", "fields": [ { "key": "subject", "label": "Subject", "labelKey": "support.supportshared.subject", "type": "text", "required": true }, { "key": "description", "label": "Description", "labelKey": "support.supportshared.description", "type": "textarea", "required": true }, { "key": "serviceName", "label": "Service", "labelKey": "support.supportshared.service", "type": "text", "required": true }, { "key": "status", "label": "Status", "labelKey": "support.supportshared.status", "type": "text", "required": true }, { "key": "priority", "label": "Priority", "labelKey": "support.supportshared.priority", "type": "text", "required": true }, { "key": "category", "label": "Category", "labelKey": "support.supportshared.category", "type": "text", "required": true }, { "key": "requesterName", "label": "Requester name", "type": "text" }, { "key": "requesterEmail", "label": "Requester email", "type": "email" }, { "key": "assignedToName", "label": "Assignee name", "type": "text" }, { "key": "assignedToEmail", "label": "Assignee email", "type": "email" } ], "titleKey": "support.mobile.actions.tickets.update.title" } ] }, { "path": "/tickets/:id", "apiPath": "/api/support/tickets/:id", "title": "Ticket", "titleKey": "support.mobile.routes.tickets.detail.title", "template": "record.detail", "dataSource": "support.tickets.detail" }, { "path": "/macros", "apiPath": "/api/support/macros", "title": "Macros", "titleKey": "support.mobile.routes.macros.title", "template": "record.list", "dataSource": "support.macros.list", "detailRoute": "/macros/:id", "actions": [ { "id": "support.macros.create", "title": "Create macro", "type": "record.create", "permission": "macros:write", "method": "POST", "path": "/api/support/macros", "fields": [ { "key": "title", "label": "Title", "labelKey": "support.supportshared.title", "type": "text", "required": true }, { "key": "body", "label": "Body", "labelKey": "support.supportshared.body", "type": "textarea", "required": true }, { "key": "visibility", "label": "Visibility", "labelKey": "support.supportshared.visibility", "type": "text", "required": true }, { "key": "suggestedStatus", "label": "Suggested status", "labelKey": "support.supportshared.suggestedStatus", "type": "text" }, { "key": "suggestedPriority", "label": "Suggested priority", "labelKey": "support.supportshared.suggestedPriority", "type": "text" } ], "titleKey": "support.mobile.actions.macros.create.title" } ] }, { "path": "/macros/:id", "apiPath": "/api/support/macros/:id", "title": "Macro", "titleKey": "support.mobile.routes.macros.title", "template": "record.detail", "dataSource": "support.macros.detail" } ] } } ], "package_manifests": [], "deployment_configs": [], "source_signals": { "api_routes": [ { "method": "ALL", "path": "*", "source_path": "apps/TopoloSupport/apps/api/src/worker.ts" } ], "ui_routes": [ { "path": "/tickets", "source_path": "apps/TopoloSupport/apps/web/src/App.tsx" }, { "path": "/tickets/new", "source_path": "apps/TopoloSupport/apps/web/src/App.tsx" }, { "path": "/tickets/:ticketId", "source_path": "apps/TopoloSupport/apps/web/src/App.tsx" }, { "path": "/operations", "source_path": "apps/TopoloSupport/apps/web/src/App.tsx" }, { "path": "/macros", "source_path": "apps/TopoloSupport/apps/web/src/App.tsx" }, { "path": "/getting-started", "source_path": "apps/TopoloSupport/apps/web/src/App.tsx" } ], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/support", "internal/apps/topolo-support" ], "present_paths": [ "applications/support", "internal/apps/topolo-support" ], "missing_paths": [], "human_reference": "/systems/topolo-support", "machine_reference": "/machine/systems/topolo-support.json", "action_examples": 26, "action_schemas": 26 }, "source_findings": [ { "type": "declared_unserved_actions", "source_path": "apps/TopoloSupport/topolo.app.json", "detail": [ "GET /api/widget" ] }, { "type": "action_coverage_configuration", "source_path": "apps/TopoloSupport/topolo.app.json", "detail": [ "* /api/auth/*: exclusion matches no served route", "* /api/support/*: exclusion matches no served route" ] } ] }, "topolo-web": { "id": "topolo-web", "name": "TopoloWeb", "slug": "topolo-web", "kind": "application", "visibility": "public", "repo_paths": [ "apps/TopoloWeb" ], "source_revisions": [ { "source_path": "apps/TopoloWeb", "repository": "apps/TopoloWeb", "revision": "30bfa2a69264ff4adb674121bac9ed20f407bf6b", "ref": "origin/staging" } ], "source_counts": { "source_files": 169, "test_files": 84, "test_cases": 0, "migration_files": 8, "database_tables": 0, "manifests": 1, "deploy_targets": 3, "actions": 44, "mobile_contracts": 1, "notifications": 7, "package_manifests": 8, "deployment_configs": 1 }, "manifests": [ { "source_path": "apps/TopoloWeb/topolo.app.json", "service_slug": "topolo-web", "name": "topoloweb", "app_id": "app_topolo_web", "compatibility_date": "2026-04-10", "primary_target": null, "environments": [ "development", "production", "staging" ], "targets": [ { "name": "web", "kind": "worker", "directory": "apps/web", "main": "src/worker.ts", "worker_name": "topolo-web-studio", "subdomain": "web", "healthcheck_path": null, "variable_names": [ "AUTH_API_URL", "INSIGHTS_SITE_KEY" ], "secret_names": [], "bindings": [ { "kind": "services", "binding": "API", "target": null } ] }, { "name": "api", "kind": "worker", "directory": "apps/api", "main": "src/index.ts", "worker_name": "topolo-web-api", "subdomain": null, "healthcheck_path": "/health", "variable_names": [ "ENVIRONMENT", "FRONTEND_URL", "NEXUS_GATEWAY_URL", "NEXUS_MODEL", "NEXUS_PROVIDER", "RUNTIME_URL", "TOPOLO_AUTH_API_URL", "TOPOLO_NOTIFY_URL" ], "secret_names": [], "bindings": [ { "kind": "d1", "binding": "TOPOLOWEB_CONTROL_DB", "target": null }, { "kind": "d1", "binding": "TOPOLOWEB_CONTENT_DB", "target": null }, { "kind": "d1", "binding": "TOPOLOWEB_EVENTS_AGENT_DB", "target": null }, { "kind": "kv", "binding": "TOPOLOWEB_PUBLISHED_KV", "target": null } ] }, { "name": "runtime", "kind": "worker", "directory": "apps/runtime", "main": "@astrojs/cloudflare/entrypoints/server", "worker_name": "topolo-web-runtime", "subdomain": null, "healthcheck_path": "/health", "variable_names": [], "secret_names": [], "bindings": [ { "kind": "kv", "binding": "SESSION", "target": null } ] } ], "notifications": [ "web.build.completed", "web.build.failed", "web.collection.import_failed", "web.domain.verification_failed", "web.domain.verification_required", "web.site.published", "web.site.unpublished" ], "notification_contract": { "source_path": "topolo.notification-contracts.json", "role": "producer", "schema_version": 1, "owner_app_id": "app_topolo_web", "events": [ { "type": "web.build.completed", "version": 1, "description": "A requested site build completed and its site state was persisted.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "build_id", "site_id", "site_name" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "build_id": { "type": "string", "minLength": 1 }, "site_id": { "type": "string", "minLength": 1 }, "site_name": { "type": "string", "minLength": 1 } }, "additionalProperties": true }, "examples": [ { "title": "Site build completed: Northstar", "body": "The generated site is ready to review.", "object_id": "webbuild_1", "occurred_at": "2026-07-20T00:00:00.000Z", "build_id": "webbuild_1", "site_id": "site_1", "site_name": "Northstar" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^web:build-completed:" }, "sensitiveFields": [] }, { "type": "web.build.failed", "version": 1, "description": "A requested site build failed and the terminal attempt was persisted.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "build_id", "site_name", "reason" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "build_id": { "type": "string", "minLength": 1 }, "site_name": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 } }, "additionalProperties": true }, "examples": [ { "title": "Site build failed: Northstar", "body": "The site payload could not be built.", "object_id": "webbuild_2", "occurred_at": "2026-07-20T00:00:00.000Z", "build_id": "webbuild_2", "site_name": "Northstar", "reason": "invalid_build_payload" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^web:build-failed:" }, "sensitiveFields": [] }, { "type": "web.collection.import_failed", "version": 1, "description": "A collection CSV import failed and the terminal attempt was persisted.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "import_id", "site_id", "collection_slug", "reason" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "import_id": { "type": "string", "minLength": 1 }, "site_id": { "type": "string", "minLength": 1 }, "collection_slug": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 } }, "additionalProperties": true }, "examples": [ { "title": "Collection import failed: products", "body": "The collection CSV was rejected.", "object_id": "webcollectionimport_1", "occurred_at": "2026-07-20T00:00:00.000Z", "import_id": "webcollectionimport_1", "site_id": "site_1", "collection_slug": "products", "reason": "invalid_headers" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^web:collection-import-failed:" }, "sensitiveFields": [] }, { "type": "web.domain.verification_failed", "version": 1, "description": "A custom-domain DNS verification attempt failed and was persisted.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "site_id", "domain_id", "hostname", "reason" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "site_id": { "type": "string", "minLength": 1 }, "domain_id": { "type": "string", "minLength": 1 }, "hostname": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 } }, "additionalProperties": true }, "examples": [ { "title": "Domain verification failed: www.example.com", "body": "The required DNS records were not visible.", "object_id": "domain_1", "occurred_at": "2026-07-20T00:00:00.000Z", "site_id": "site_1", "domain_id": "domain_1", "hostname": "www.example.com", "reason": "dns_records_missing" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^web:domain-verification-failed:" }, "sensitiveFields": [] }, { "type": "web.domain.verification_required", "version": 1, "description": "A custom domain was persisted and requires DNS ownership verification.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "site_id", "domain_id", "hostname", "dns_target", "verification_token" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "site_id": { "type": "string", "minLength": 1 }, "domain_id": { "type": "string", "minLength": 1 }, "hostname": { "type": "string", "minLength": 1 }, "dns_target": { "type": "string", "minLength": 1 }, "verification_token": { "type": "string", "minLength": 1 } }, "additionalProperties": true }, "examples": [ { "title": "Verify www.example.com", "body": "Add the required DNS records.", "object_id": "domain_1", "occurred_at": "2026-07-20T00:00:00.000Z", "site_id": "site_1", "domain_id": "domain_1", "hostname": "www.example.com", "dns_target": "sites.topolo.app", "verification_token": "verify_123" } ], "dataClassification": "confidential", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^web:domain-verification-required:" }, "sensitiveFields": [ "verification_token" ] }, { "type": "web.site.published", "version": 1, "description": "A site version was published and persisted.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "site_id", "version_id", "version_number" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "site_id": { "type": "string", "minLength": 1 }, "version_id": { "type": "string", "minLength": 1 }, "version_number": { "type": "integer", "minimum": 1 } }, "additionalProperties": true }, "examples": [ { "title": "Site published: Northstar", "body": "Version 2 is now live.", "object_id": "site_1", "occurred_at": "2026-07-20T00:00:00.000Z", "site_id": "site_1", "version_id": "version_2", "version_number": 2 } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^web:site-published:" }, "sensitiveFields": [] }, { "type": "web.site.unpublished", "version": 1, "description": "A published site was moved back to draft and its public cache was purged.", "status": "published", "payloadSchema": { "type": "object", "required": [ "title", "body", "object_id", "occurred_at", "site_id" ], "properties": { "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "object_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "site_id": { "type": "string", "minLength": 1 } }, "additionalProperties": true }, "examples": [ { "title": "Site unpublished: Northstar", "body": "The public site is no longer serving its published version.", "object_id": "site_1", "occurred_at": "2026-07-20T00:00:00.000Z", "site_id": "site_1" } ], "dataClassification": "internal", "recipients": { "modes": [ "organization_member" ], "externalAddress": "forbidden" }, "idempotency": { "required": true, "pattern": "^web:site-unpublished:" }, "sensitiveFields": [] } ] }, "actions": [ { "name": "organizations.data.export", "title": "Export organization data", "description": "Export all TopoloWeb workspaces, sites, content, submissions, agent activity, operational records, and uploaded-asset metadata owned by the authenticated organization without preview, domain-verification, or client-address credentials.", "permission": "privacy:read", "method": "GET", "path": "/api/organizations/data/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-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/organizations/data/export", "body": null }, "effects": "Reads state through GET /api/organizations/data/export without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/organizations/data/export", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "organizations.data.erase", "title": "Erase organization data", "description": "Permanently erase all TopoloWeb data owned by the authenticated organization across control, content, events and agent databases plus published KV objects while retaining backups under policy.", "permission": "privacy:write", "method": "DELETE", "path": "/api/organizations/data/erase", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "confirmation": "ERASE" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/organizations/data/erase", "body": null }, "effects": "May change state through DELETE /api/organizations/data/erase. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/organizations/data/erase", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "workspaces.delete", "title": "Delete workspace", "description": "Permanently delete an empty, non-default TopoloWeb workspace.", "permission": "workspace:delete", "method": "DELETE", "path": "/api/workspaces/{workspaceId}", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "ok", "workspaceId" ], "additionalProperties": false }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/applications/web#workspace-management", "resource": { "kind": "workspace", "idPath": "workspaceId" }, "effects": [ "Confirms the TopoloWeb workspace is empty, then asks Topolo Auth to archive its canonical identity." ], "errors": [ { "status": 409, "code": "workspace_delete_blocked", "recovery": "Remove owned sites or select another default workspace, then retry the deletion." } ], "verify": [ "Call app_topolo_auth.workspaces.list and confirm the archived workspace id is absent." ], "nextActionIds": [ "app_topolo_auth.workspaces.list" ] }, "documentation": { "example_input": { "workspaceId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/workspaces/example", "body": null }, "effects": "Confirms the TopoloWeb workspace is empty, then asks Topolo Auth to archive its canonical identity.", "verification": [ "Call app_topolo_auth.workspaces.list and confirm the archived workspace id is absent." ], "recovery": [ "409 workspace_delete_blocked: Remove owned sites or select another default workspace, then retry the deletion." ], "docs_url": "https://docs.topolo.app/applications/web#workspace-management", "resource": { "kind": "workspace", "idPath": "workspaceId" }, "next_action_ids": [ "app_topolo_auth.workspaces.list" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/workspaces/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "forms.submissions.create", "title": "Forms Submissions Create", "description": "Call POST /forms/{formId}/submissions.", "method": "POST", "path": "/api/forms/{formId}/submissions", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "formId": { "type": "string", "minLength": 1 }, "siteId": { "type": "string", "minLength": 1 }, "pageId": { "type": "string", "minLength": 1 }, "turnstileToken": { "type": "string", "minLength": 1 }, "cf-turnstile-response": { "type": "string", "minLength": 1 } }, "required": [ "formId", "siteId", "pageId" ], "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Forms Submissions Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "public", "documentation": { "example_input": { "formId": "example", "siteId": "example", "pageId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/forms/example/submissions", "body": { "formId": "example", "siteId": "example", "pageId": "example" } }, "effects": "May change state through POST /api/forms/{formId}/submissions. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/forms/*/submissions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.create", "title": "Sites Create", "description": "Call POST /studio/sites.", "method": "POST", "path": "/api/studio/sites", "permission": "studio:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "intent": { "type": "string", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "minLength": 1 }, "audience": { "type": "string", "minLength": 1 }, "offer": { "type": "string", "minLength": 1 }, "tone": { "type": "string", "minLength": 1 }, "location": { "type": "string", "minLength": 1 }, "differentiators": { "type": "array", "items": { "type": "string" } }, "goals": { "type": "array", "items": { "type": "string" } }, "prompt": { "type": "string", "minLength": 1 } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "name": "example", "businessType": "example", "audience": "example", "offer": "example", "tone": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites", "body": { "name": "example", "businessType": "example", "audience": "example", "offer": "example", "tone": "example" } }, "effects": "May change state through POST /api/studio/sites. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "id": "app_topolo_web.sites.build", "name": "sites.build", "title": "Build site from canonical content", "description": "Create a TopoloWeb site from a full canonical SiteContent payload and optionally publish it. This is the agent-safe Topolo Developers action path for Codex, Claude, CLI, and MCP site builds.", "method": "POST", "path": "/api/studio/sites/build", "permission": "studio:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Build TopoloWeb site", "type": "object", "description": "Create a site from complete canonical content and optionally publish it.", "properties": { "site": { "$ref": "#/$defs/createSite" }, "content": { "$ref": "#/$defs/siteContent" }, "publish": { "type": "boolean", "description": "Publish the first immutable version after quality validation." }, "publishLabel": { "type": "string", "description": "Optional first-version label.", "minLength": 1 } }, "required": [ "site", "content" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } }, "target": "api", "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "description": "New site state, quality evidence, preview coordinates, and optional first published version.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } }, "version": { "description": "First published version when publish=true; omitted otherwise.", "anyOf": [ { "$ref": "#/$defs/siteVersion" }, { "type": "null" } ] }, "urls": { "$ref": "#/$defs/siteUrls" } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions", "urls" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/applications/web", "resource": { "kind": "site", "idPath": "site.id", "versionPath": "version.id" }, "effects": [ "Creates one site and draft content.", "Publishes only when publish=true." ], "errors": [ { "status": 400, "code": "invalid_site_payload", "recovery": "Correct the payload using sites.capabilities.get, then call sites.validate." }, { "status": 422, "code": "publish_blocked", "recovery": "Resolve every error in qualityReport before publishing." } ], "verify": [ "Open urls.previewUrl at every required viewport.", "When published, open urls.publicUrl and confirm the intended version." ], "rollbackActionId": "app_topolo_web.sites.versions.restore", "nextActionIds": [ "app_topolo_web.sites.preview.get", "app_topolo_web.sites.publish.preflight" ] }, "authorizationMode": "static", "documentation": { "example_input": { "site": { "name": "example", "businessType": "example", "audience": "example", "offer": "example", "tone": "example" }, "content": { "intent": "business_site", "siteTitle": "example", "siteDescription": "example", "contactEmail": "user@example.com", "navigation": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "href": "example", "kind": "primary" } ], "footerNavigation": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "href": "example", "kind": "primary" } ], "menus": [ { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "placement": "custom", "items": [] } ], "styleClasses": [ { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "targetKind": "container", "targetScope": "section", "style": { "backgroundColor": "example", "backgroundImageUrl": "https://example.com", "backgroundMode": "cover" } } ], "theme": { "primary": "example", "secondary": "example", "surface": "example", "ink": "example", "muted": "example", "accent": "example", "accentSoft": "example", "glow": "example", "headingFont": "example", "bodyFont": "example", "radius": "example" }, "document": { "version": 1, "pages": [] }, "collections": [ { "id": "00000000-0000-4000-8000-000000000000", "slug": "example", "kind": "apps", "label": "example", "items": [] } ], "codeSnippets": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "slot": "head", "code": "example", "enabled": true } ] } }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/build", "body": { "site": { "name": "example", "businessType": "example", "audience": "example", "offer": "example", "tone": "example" }, "content": { "intent": "business_site", "siteTitle": "example", "siteDescription": "example", "contactEmail": "user@example.com", "navigation": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "href": "example", "kind": "primary" } ], "footerNavigation": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "href": "example", "kind": "primary" } ], "menus": [ { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "placement": "custom", "items": [] } ], "styleClasses": [ { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "targetKind": "container", "targetScope": "section", "style": { "backgroundColor": "example", "backgroundImageUrl": "https://example.com", "backgroundMode": "cover" } } ], "theme": { "primary": "example", "secondary": "example", "surface": "example", "ink": "example", "muted": "example", "accent": "example", "accentSoft": "example", "glow": "example", "headingFont": "example", "bodyFont": "example", "radius": "example" }, "document": { "version": 1, "pages": [] }, "collections": [ { "id": "00000000-0000-4000-8000-000000000000", "slug": "example", "kind": "apps", "label": "example", "items": [] } ], "codeSnippets": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "slot": "head", "code": "example", "enabled": true } ] } } }, "effects": "Creates one site and draft content. Publishes only when publish=true.", "verification": [ "Open urls.previewUrl at every required viewport.", "When published, open urls.publicUrl and confirm the intended version." ], "recovery": [ "400 invalid_site_payload: Correct the payload using sites.capabilities.get, then call sites.validate.", "422 publish_blocked: Resolve every error in qualityReport before publishing." ], "docs_url": "https://docs.topolo.app/applications/web", "resource": { "kind": "site", "idPath": "site.id", "versionPath": "version.id" }, "next_action_ids": [ "app_topolo_web.sites.preview.get", "app_topolo_web.sites.publish.preflight" ], "rollback_action_id": "app_topolo_web.sites.versions.restore" }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/build", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.capabilities.get", "title": "Get site agent capabilities", "description": "Get the canonical repository-independent site schema, block catalog, examples, viewports, and workflow.", "permission": "studio:read", "method": "GET", "path": "/api/studio/sites/capabilities", "readOnly": true, "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", "description": "TopoloWeb clean-room agent capabilities and canonical schemas.", "properties": { "contractVersion": { "type": "string", "description": "Version of the public agent contract.", "minLength": 1 }, "docsUrl": { "type": "string", "description": "Public operational documentation URL.", "format": "uri" }, "siteContentSchema": { "type": "object", "description": "Canonical SiteContent JSON Schema.", "additionalProperties": true }, "buildInputSchema": { "type": "object", "description": "sites.build input JSON Schema.", "additionalProperties": true }, "blockCatalog": { "type": "array", "description": "Renderer-backed block catalog with fields and design capabilities.", "items": { "type": "object", "description": "One block capability entry.", "additionalProperties": true } }, "compositionRecipes": { "type": "array", "description": "Audience-specific composition plans that use the block catalog deliberately.", "items": { "type": "object", "description": "One complete composition recipe.", "properties": { "id": { "type": "string", "description": "Stable recipe identifier.", "enum": [ "angel-investor", "marketplace-developer", "partner-channel", "platform-pitch", "venture-investor" ] }, "title": { "type": "string", "description": "Human-readable recipe title.", "minLength": 1 }, "audience": { "type": "string", "description": "Audience the composition is designed to persuade.", "minLength": 1 }, "visualThesis": { "type": "string", "description": "Unifying visual direction for the site.", "minLength": 1 }, "contentPlan": { "type": "array", "description": "Ordered content and block plan.", "items": { "type": "object", "description": "One block choice and its narrative job.", "properties": { "purpose": { "type": "string", "description": "Narrative purpose of the block.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "itemsPlacement": { "type": "string", "description": "Optional repeated-item placement.", "enum": [ "left", "right" ] }, "note": { "type": "string", "description": "Implementation guidance for this block.", "minLength": 1 } }, "required": [ "purpose", "kind", "note" ], "additionalProperties": false } }, "interactionThesis": { "type": "array", "description": "Interaction and reading-flow principles.", "items": { "type": "string", "description": "One interaction principle.", "minLength": 1 } }, "avoid": { "type": "array", "description": "Composition failure modes to avoid.", "items": { "type": "string", "description": "One failure mode.", "minLength": 1 } } }, "required": [ "id", "title", "audience", "visualThesis", "contentPlan", "interactionThesis", "avoid" ], "additionalProperties": false } }, "viewports": { "type": "array", "description": "Required responsive QA viewports.", "items": { "type": "object", "description": "One required QA viewport.", "properties": { "id": { "type": "string", "description": "Viewport identifier.", "enum": [ "mobile", "tablet", "desktop", "4k" ] }, "width": { "type": "integer", "description": "Viewport width in CSS pixels.", "minimum": 1 }, "description": { "type": "string", "description": "What this viewport verifies.", "minLength": 1 } }, "required": [ "id", "width", "description" ], "additionalProperties": false } }, "workflow": { "type": "array", "description": "Ordered clean-room build workflow.", "items": { "type": "string", "description": "One workflow step.", "minLength": 1 } }, "examples": { "type": "array", "description": "Canonical generated examples for every supported site intent.", "items": { "type": "object", "description": "One named intent example.", "properties": { "id": { "type": "string", "description": "Stable example identifier.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "content": { "$ref": "#/$defs/siteContent" } }, "required": [ "id", "intent", "content" ], "additionalProperties": false } } }, "required": [ "contractVersion", "docsUrl", "siteContentSchema", "buildInputSchema", "blockCatalog", "compositionRecipes", "viewports", "workflow", "examples" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/studio/sites/capabilities", "body": null }, "effects": "Reads state through GET /api/studio/sites/capabilities without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/studio/sites/capabilities", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.validate", "title": "Validate canonical site payload", "description": "Validate complete site content and return deterministic quality findings without persisting changes.", "permission": "studio:read", "method": "POST", "path": "/api/studio/sites/validate", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Validate TopoloWeb site", "type": "object", "description": "Validate a complete canonical site payload without persisting it.", "properties": { "site": { "$ref": "#/$defs/createSite" }, "content": { "$ref": "#/$defs/siteContent" } }, "required": [ "site", "content" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "description": "Non-persisting TopoloWeb validation result.", "properties": { "valid": { "type": "boolean", "description": "Whether the payload is structurally valid and has no blocking quality issues." }, "qualityReport": { "$ref": "#/$defs/qualityReport" } }, "required": [ "valid", "qualityReport" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "site": { "name": "example", "businessType": "example", "audience": "example", "offer": "example", "tone": "example" }, "content": { "intent": "business_site", "siteTitle": "example", "siteDescription": "example", "contactEmail": "user@example.com", "navigation": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "href": "example", "kind": "primary" } ], "footerNavigation": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "href": "example", "kind": "primary" } ], "menus": [ { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "placement": "custom", "items": [] } ], "styleClasses": [ { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "targetKind": "container", "targetScope": "section", "style": { "backgroundColor": "example", "backgroundImageUrl": "https://example.com", "backgroundMode": "cover" } } ], "theme": { "primary": "example", "secondary": "example", "surface": "example", "ink": "example", "muted": "example", "accent": "example", "accentSoft": "example", "glow": "example", "headingFont": "example", "bodyFont": "example", "radius": "example" }, "document": { "version": 1, "pages": [] }, "collections": [ { "id": "00000000-0000-4000-8000-000000000000", "slug": "example", "kind": "apps", "label": "example", "items": [] } ], "codeSnippets": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "slot": "head", "code": "example", "enabled": true } ] } }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/validate", "body": { "site": { "name": "example", "businessType": "example", "audience": "example", "offer": "example", "tone": "example" }, "content": { "intent": "business_site", "siteTitle": "example", "siteDescription": "example", "contactEmail": "user@example.com", "navigation": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "href": "example", "kind": "primary" } ], "footerNavigation": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "href": "example", "kind": "primary" } ], "menus": [ { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "placement": "custom", "items": [] } ], "styleClasses": [ { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "targetKind": "container", "targetScope": "section", "style": { "backgroundColor": "example", "backgroundImageUrl": "https://example.com", "backgroundMode": "cover" } } ], "theme": { "primary": "example", "secondary": "example", "surface": "example", "ink": "example", "muted": "example", "accent": "example", "accentSoft": "example", "glow": "example", "headingFont": "example", "bodyFont": "example", "radius": "example" }, "document": { "version": 1, "pages": [] }, "collections": [ { "id": "00000000-0000-4000-8000-000000000000", "slug": "example", "kind": "apps", "label": "example", "items": [] } ], "codeSnippets": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "slot": "head", "code": "example", "enabled": true } ] } } }, "effects": "Reads state through POST /api/studio/sites/validate without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/validate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.bootstrap", "title": "Get site bootstrap", "description": "Get the site list and selected site for the active workspace.", "permission": "studio:read", "method": "GET", "path": "/api/studio/sites/bootstrap", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "site_id": "00000000-0000-4000-8000-000000000000" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/studio/sites/bootstrap", "body": null }, "effects": "Reads state through GET /api/studio/sites/bootstrap without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/studio/sites/bootstrap", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.update", "title": "Sites Update", "description": "Call PUT /studio/sites/{siteId}.", "method": "PUT", "path": "/api/studio/sites/{siteId}", "permission": "studio:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "brief": { "type": "object", "properties": { "intent": { "type": "string", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessName": { "type": "string", "minLength": 1 }, "businessType": { "type": "string", "minLength": 1 }, "location": { "type": "string", "minLength": 1 }, "audience": { "type": "string", "minLength": 1 }, "offer": { "type": "string", "minLength": 1 }, "tone": { "type": "string", "minLength": 1 }, "differentiators": { "type": "array", "items": { "type": "string" } }, "goals": { "type": "array", "items": { "type": "string" } }, "prompt": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "theme": { "type": "object", "properties": { "primary": { "type": "string", "minLength": 1 }, "secondary": { "type": "string", "minLength": 1 }, "surface": { "type": "string", "minLength": 1 }, "ink": { "type": "string", "minLength": 1 }, "muted": { "type": "string", "minLength": 1 }, "accent": { "type": "string", "minLength": 1 }, "accentSoft": { "type": "string", "minLength": 1 }, "glow": { "type": "string", "minLength": 1 }, "headingFont": { "type": "string", "minLength": 1 }, "bodyFont": { "type": "string", "minLength": 1 }, "radius": { "type": "string", "minLength": 1 }, "brandLogoUrl": { "type": "string" }, "brandLogoAlt": { "type": "string" }, "brandLogoWidth": { "type": "string" }, "brandLogoHeight": { "type": "string" }, "pageDefaults": { "type": "object", "properties": { "sectionPaddingTop": { "type": "number", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "minimum": 0 }, "sectionMarginTop": { "type": "number" }, "sectionMarginBottom": { "type": "number" }, "sectionMarginLeft": { "type": "number" }, "sectionMarginRight": { "type": "number" }, "headingSize": { "type": "number", "minimum": 1 }, "headingLineHeight": { "type": "number", "minimum": 0.5 }, "bodySize": { "type": "number", "minimum": 1 }, "bodyLineHeight": { "type": "number", "minimum": 0.5 }, "cardPadding": { "type": "number", "minimum": 0 }, "layoutGap": { "type": "number", "minimum": 0 }, "responsive": { "type": "object", "propertyNames": { "type": "string", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "type": "object", "properties": { "sectionPaddingTop": { "type": "number", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "minimum": 0 }, "sectionMarginTop": { "type": "number" }, "sectionMarginBottom": { "type": "number" }, "sectionMarginLeft": { "type": "number" }, "sectionMarginRight": { "type": "number" }, "headingSize": { "type": "number", "minimum": 1 }, "headingLineHeight": { "type": "number", "minimum": 0.5 }, "bodySize": { "type": "number", "minimum": 1 }, "bodyLineHeight": { "type": "number", "minimum": 0.5 }, "cardPadding": { "type": "number", "minimum": 0 }, "layoutGap": { "type": "number", "minimum": 0 } }, "additionalProperties": false } } }, "additionalProperties": false }, "customCss": { "type": "string" } }, "additionalProperties": false }, "navigation": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "href": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "minLength": 1 }, "targetBlank": { "type": "boolean" } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false } }, "footerNavigation": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "href": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "minLength": 1 }, "targetBlank": { "type": "boolean" } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false } }, "menus": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "placement": { "type": "string", "const": "custom" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "href": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "minLength": 1 }, "targetBlank": { "type": "boolean" } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false } }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "minLength": 1 }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "body": { "type": "string" }, "meta": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "badge": { "type": "string", "minLength": 1 }, "href": { "type": "string", "minLength": 1 }, "targetBlank": { "type": "boolean" }, "imageUrl": { "type": "string" }, "alt": { "type": "string" } }, "required": [ "id", "title", "body" ], "additionalProperties": false } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false } }, "styleClasses": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "targetKind": { "type": "string", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "const": "section" }, "style": { "type": "object", "properties": { "backgroundColor": { "type": "string" }, "backgroundImageUrl": { "type": "string" }, "backgroundMode": { "type": "string", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number" }, "paddingBottom": { "type": "number" }, "paddingBlockLinked": { "type": "boolean" }, "paddingLeft": { "type": "number" }, "paddingRight": { "type": "number" }, "paddingInlineLinked": { "type": "boolean" }, "marginTop": { "type": "number" }, "marginBottom": { "type": "number" }, "marginBlockLinked": { "type": "boolean" }, "marginLeft": { "type": "number" }, "marginRight": { "type": "number" }, "marginInlineLinked": { "type": "boolean" }, "borderWidth": { "type": "number" }, "borderStyle": { "type": "string", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string" }, "borderRadius": { "type": "number" }, "headingSize": { "type": "number" }, "headingLineHeight": { "type": "number" }, "bodySize": { "type": "number" }, "bodyLineHeight": { "type": "number" }, "cardPadding": { "type": "number" }, "columnCount": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 }, { "type": "number", "const": 4 } ] }, "columnSpans": { "type": "array", "items": { "type": "number" } }, "layoutGap": { "type": "number" }, "nestedSectionPadding": { "type": "number" }, "mediaAspectRatio": { "type": "string", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number" }, "mediaFocalY": { "type": "number" }, "dividerTop": { "type": "boolean" }, "dividerBottom": { "type": "boolean" }, "dividerThickness": { "type": "number" }, "dividerWidth": { "type": "number" }, "dividerLineStyle": { "type": "string", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string" }, "responsive": { "type": "object", "propertyNames": { "type": "string", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "type": "object", "properties": { "backgroundColor": { "type": "string" }, "backgroundImageUrl": { "type": "string" }, "backgroundMode": { "type": "string", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number" }, "paddingBottom": { "type": "number" }, "paddingBlockLinked": { "type": "boolean" }, "paddingLeft": { "type": "number" }, "paddingRight": { "type": "number" }, "paddingInlineLinked": { "type": "boolean" }, "marginTop": { "type": "number" }, "marginBottom": { "type": "number" }, "marginBlockLinked": { "type": "boolean" }, "marginLeft": { "type": "number" }, "marginRight": { "type": "number" }, "marginInlineLinked": { "type": "boolean" }, "borderWidth": { "type": "number" }, "borderStyle": { "type": "string", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string" }, "borderRadius": { "type": "number" }, "headingSize": { "type": "number" }, "headingLineHeight": { "type": "number" }, "bodySize": { "type": "number" }, "bodyLineHeight": { "type": "number" }, "cardPadding": { "type": "number" }, "columnCount": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 }, { "type": "number", "const": 4 } ] }, "columnSpans": { "type": "array", "items": { "type": "number" } }, "layoutGap": { "type": "number" }, "nestedSectionPadding": { "type": "number" }, "mediaAspectRatio": { "type": "string", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number" }, "mediaFocalY": { "type": "number" }, "dividerTop": { "type": "boolean" }, "dividerBottom": { "type": "boolean" }, "dividerThickness": { "type": "number" }, "dividerWidth": { "type": "number" }, "dividerLineStyle": { "type": "string", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "targetKind": { "type": "string", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "const": "item" }, "style": { "type": "object", "properties": { "padding": { "type": "number" }, "radius": { "type": "number" }, "borderWidth": { "type": "number" }, "borderStyle": { "type": "string", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string" }, "imageFit": { "type": "string", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number" }, "imageFocalY": { "type": "number" }, "textPadding": { "type": "number" }, "textRadius": { "type": "number" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number" }, "headingLineHeight": { "type": "number" }, "bodySize": { "type": "number" }, "bodyLineHeight": { "type": "number" }, "responsive": { "type": "object", "propertyNames": { "type": "string", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "type": "object", "properties": { "padding": { "type": "number" }, "radius": { "type": "number" }, "borderWidth": { "type": "number" }, "borderStyle": { "type": "string", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string" }, "imageFit": { "type": "string", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number" }, "imageFocalY": { "type": "number" }, "textPadding": { "type": "number" }, "textRadius": { "type": "number" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number" }, "headingLineHeight": { "type": "number" }, "bodySize": { "type": "number" }, "bodyLineHeight": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] } }, "codeSnippets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "slot": { "type": "string", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "label", "slot", "code" ], "additionalProperties": false } }, "seo": { "type": "object", "properties": { "titleTemplate": { "type": "string", "minLength": 1 }, "metaTitle": { "type": "string", "minLength": 1 }, "metaDescription": { "type": "string", "minLength": 1 }, "faviconUrl": { "type": "string", "minLength": 1 }, "openGraphImageUrl": { "type": "string", "minLength": 1 }, "canonicalUrl": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "announcementBar": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean" }, "text": { "type": "string", "minLength": 1 }, "href": { "type": "string", "minLength": 1 } }, "required": [ "enabled", "text" ], "additionalProperties": false }, { "type": "null" } ] }, "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/studio/sites/example", "body": { "siteId": "example" } }, "effects": "May change state through PUT /api/studio/sites/{siteId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/studio/sites/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.unpublish", "title": "Unpublish site", "description": "Remove the active published version from one site.", "permission": "studio:write", "method": "POST", "path": "/api/studio/sites/{siteId}/unpublish", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/example/unpublish", "body": { "siteId": "example" } }, "effects": "May change state through POST /api/studio/sites/{siteId}/unpublish. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/unpublish", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.archive", "title": "Archive site", "description": "Archive one site.", "permission": "studio:write", "method": "POST", "path": "/api/studio/sites/{siteId}/archive", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/example/archive", "body": { "siteId": "example" } }, "effects": "May change state through POST /api/studio/sites/{siteId}/archive. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/archive", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.delete", "title": "Delete site", "description": "Permanently delete one site and its owned content.", "permission": "studio:write", "method": "DELETE", "path": "/api/studio/sites/{siteId}", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/studio/sites/example", "body": null }, "effects": "May change state through DELETE /api/studio/sites/{siteId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/studio/sites/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.collections.update", "title": "Sites Collections Update", "description": "Call PUT /studio/sites/{siteId}/collections.", "method": "PUT", "path": "/api/studio/sites/{siteId}/collections", "permission": "studio:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "collections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "minLength": 1 }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "body": { "type": "string" }, "meta": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "badge": { "type": "string", "minLength": 1 }, "href": { "type": "string", "minLength": 1 }, "targetBlank": { "type": "boolean" }, "imageUrl": { "type": "string" }, "alt": { "type": "string" } }, "required": [ "id", "title", "body" ], "additionalProperties": false } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false } } }, "required": [ "siteId", "collections" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Collections Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example", "collections": [ { "id": "00000000-0000-4000-8000-000000000000", "slug": "example", "kind": "apps", "label": "example", "items": [ { "id": "00000000-0000-4000-8000-000000000000", "title": "example", "body": "example" } ] } ] }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/studio/sites/example/collections", "body": { "siteId": "example", "collections": [ { "id": "00000000-0000-4000-8000-000000000000", "slug": "example", "kind": "apps", "label": "example", "items": [ { "id": "00000000-0000-4000-8000-000000000000", "title": "example", "body": "example" } ] } ] } }, "effects": "May change state through PUT /api/studio/sites/{siteId}/collections. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/studio/sites/*/collections", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.collections.import", "title": "Import site collection", "description": "Import a CSV into one site collection and persist the import result.", "permission": "studio:write", "method": "POST", "path": "/api/studio/sites/{siteId}/collections/import", "authorizationMode": "static", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "minLength": 1 }, "csv": { "type": "string", "minLength": 1, "maxLength": 1048576 } }, "required": [ "siteId", "slug", "kind", "label", "csv" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "documentation": { "example_input": { "siteId": "example", "slug": "example", "kind": "apps", "label": "example", "csv": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/example/collections/import", "body": { "siteId": "example", "slug": "example", "kind": "apps", "label": "example", "csv": "example" } }, "effects": "May change state through POST /api/studio/sites/{siteId}/collections/import. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/collections/import", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.code_snippets.create", "title": "Sites Code Snippets Create", "description": "Call POST /studio/sites/{siteId}/code-snippets.", "method": "POST", "path": "/api/studio/sites/{siteId}/code-snippets", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "slot": { "type": "string", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string" }, "enabled": { "type": "boolean" }, "siteId": { "type": "string", "minLength": 1 } }, "required": [ "label", "slot", "code", "siteId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Code Snippets Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "label": "example", "slot": "head", "code": "example", "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/example/code-snippets", "body": { "label": "example", "slot": "head", "code": "example", "siteId": "example" } }, "effects": "May change state through POST /api/studio/sites/{siteId}/code-snippets. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/code-snippets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.code_snippets.update", "title": "Sites Code Snippets Update", "description": "Call PUT /studio/sites/{siteId}/code-snippets/{snippetId}.", "method": "PUT", "path": "/api/studio/sites/{siteId}/code-snippets/{snippetId}", "permission": "settings:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "slot": { "type": "string", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string" }, "enabled": { "type": "boolean" }, "siteId": { "type": "string", "minLength": 1 }, "snippetId": { "type": "string", "minLength": 1 } }, "required": [ "label", "slot", "code", "siteId", "snippetId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Code Snippets Update.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "label": "example", "slot": "head", "code": "example", "siteId": "example", "snippetId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "PUT", "path": "/api/studio/sites/example/code-snippets/example", "body": { "label": "example", "slot": "head", "code": "example", "siteId": "example", "snippetId": "example" } }, "effects": "May change state through PUT /api/studio/sites/{siteId}/code-snippets/{snippetId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "PUT /api/studio/sites/*/code-snippets/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.code_snippets.delete", "title": "Sites Code Snippets Delete", "description": "Call DELETE /studio/sites/{siteId}/code-snippets/{snippetId}.", "method": "DELETE", "path": "/api/studio/sites/{siteId}/code-snippets/{snippetId}", "permission": "settings:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "snippetId": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "snippetId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Code Snippets Delete.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example", "snippetId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/studio/sites/example/code-snippets/example", "body": null }, "effects": "May change state through DELETE /api/studio/sites/{siteId}/code-snippets/{snippetId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/studio/sites/*/code-snippets/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.agent_sessions.create", "title": "Sites Agent Sessions Create", "description": "Call POST /studio/sites/{siteId}/agent/sessions.", "method": "POST", "path": "/api/studio/sites/{siteId}/agent/sessions", "permission": "studio:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Agent Sessions Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/applications/web#agent-editing", "resource": { "kind": "agent_session", "idPath": "session.id" }, "effects": [ "Creates one reviewable editing session without changing site content." ], "errors": [ { "status": 401, "code": "authentication_required", "recovery": "Authenticate again with Topolo Auth, then retry once." }, { "status": 403, "code": "permission_denied", "recovery": "Use a credential with studio:write for the selected workspace." }, { "status": 404, "code": "site_not_found", "recovery": "List sites in the selected workspace and retry with a returned site id." } ], "verify": [ "Call app_topolo_web.sites.agent_sessions.get with the returned session.id." ], "nextActionIds": [ "app_topolo_web.sites.agent_sessions.messages.create" ] }, "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/example/agent/sessions", "body": { "siteId": "example" } }, "effects": "Creates one reviewable editing session without changing site content.", "verification": [ "Call app_topolo_web.sites.agent_sessions.get with the returned session.id." ], "recovery": [ "401 authentication_required: Authenticate again with Topolo Auth, then retry once.", "403 permission_denied: Use a credential with studio:write for the selected workspace.", "404 site_not_found: List sites in the selected workspace and retry with a returned site id." ], "docs_url": "https://docs.topolo.app/applications/web#agent-editing", "resource": { "kind": "agent_session", "idPath": "session.id" }, "next_action_ids": [ "app_topolo_web.sites.agent_sessions.messages.create" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/agent/sessions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.agent_sessions.messages.create", "title": "Sites Agent Sessions Messages Create", "description": "Call POST /studio/sites/{siteId}/agent/sessions/{sessionId}/messages.", "method": "POST", "path": "/api/studio/sites/{siteId}/agent/sessions/{sessionId}/messages", "permission": "studio:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "sessionId", "content" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Agent Sessions Messages Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "agentContract": { "docsUrl": "https://docs.topolo.app/applications/web#agent-editing", "resource": { "kind": "agent_proposal", "idPath": "proposals.0.id" }, "effects": [ "Adds one user instruction and creates a pending, reviewable site proposal." ], "errors": [ { "status": 503, "code": "dependency_unavailable", "recovery": "Keep the current session, wait for the proposal dependency to recover, then send a new instruction once." } ], "verify": [ "Call app_topolo_web.sites.agent_sessions.get and confirm the returned pending proposal matches the instruction." ], "nextActionIds": [ "app_topolo_web.sites.agent_sessions.proposals.apply", "app_topolo_web.sites.agent_sessions.proposals.reject" ] }, "documentation": { "example_input": { "siteId": "example", "sessionId": "example", "content": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/example/agent/sessions/example/messages", "body": { "siteId": "example", "sessionId": "example", "content": "example" } }, "effects": "Adds one user instruction and creates a pending, reviewable site proposal.", "verification": [ "Call app_topolo_web.sites.agent_sessions.get and confirm the returned pending proposal matches the instruction." ], "recovery": [ "503 dependency_unavailable: Keep the current session, wait for the proposal dependency to recover, then send a new instruction once." ], "docs_url": "https://docs.topolo.app/applications/web#agent-editing", "resource": { "kind": "agent_proposal", "idPath": "proposals.0.id" }, "next_action_ids": [ "app_topolo_web.sites.agent_sessions.proposals.apply", "app_topolo_web.sites.agent_sessions.proposals.reject" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/agent/sessions/*/messages", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.agent_sessions.proposals.apply", "title": "Sites Agent Sessions Proposals Apply", "description": "Call POST /studio/sites/{siteId}/agent/sessions/{sessionId}/proposals/{proposalId}/apply.", "method": "POST", "path": "/api/studio/sites/{siteId}/agent/sessions/{sessionId}/proposals/{proposalId}/apply", "permission": "studio:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 }, "proposalId": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "sessionId", "proposalId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Agent Sessions Proposals Apply.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example", "sessionId": "example", "proposalId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/example/agent/sessions/example/proposals/example/apply", "body": { "siteId": "example", "sessionId": "example", "proposalId": "example" } }, "effects": "May change state through POST /api/studio/sites/{siteId}/agent/sessions/{sessionId}/proposals/{proposalId}/apply. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/agent/sessions/*/proposals/*/apply", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.agent_sessions.proposals.reject", "title": "Sites Agent Sessions Proposals Reject", "description": "Call POST /studio/sites/{siteId}/agent/sessions/{sessionId}/proposals/{proposalId}/reject.", "method": "POST", "path": "/api/studio/sites/{siteId}/agent/sessions/{sessionId}/proposals/{proposalId}/reject", "permission": "studio:write", "requiresConfirmation": true, "destructive": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 }, "proposalId": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "sessionId", "proposalId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Agent Sessions Proposals Reject.", "additionalProperties": true }, "readOnly": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example", "sessionId": "example", "proposalId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/example/agent/sessions/example/proposals/example/reject", "body": { "siteId": "example", "sessionId": "example", "proposalId": "example" } }, "effects": "May change state through POST /api/studio/sites/{siteId}/agent/sessions/{sessionId}/proposals/{proposalId}/reject. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/agent/sessions/*/proposals/*/reject", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.generate", "title": "Sites Generate", "description": "Call POST /studio/sites/{siteId}/generate.", "method": "POST", "path": "/api/studio/sites/{siteId}/generate", "permission": "studio:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "intent": { "type": "string", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessName": { "type": "string", "minLength": 1 }, "businessType": { "type": "string", "minLength": 1 }, "location": { "type": "string", "minLength": 1 }, "audience": { "type": "string", "minLength": 1 }, "offer": { "type": "string", "minLength": 1 }, "tone": { "type": "string", "minLength": 1 }, "differentiators": { "type": "array", "items": { "type": "string" } }, "goals": { "type": "array", "items": { "type": "string" } }, "prompt": { "type": "string", "minLength": 1 }, "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Generate.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/example/generate", "body": { "siteId": "example" } }, "effects": "May change state through POST /api/studio/sites/{siteId}/generate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/generate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.document_nodes.regenerate", "title": "Sites Document Nodes Regenerate", "description": "Call POST /studio/sites/{siteId}/document/nodes/{nodeId}/regenerate.", "method": "POST", "path": "/api/studio/sites/{siteId}/document/nodes/{nodeId}/regenerate", "permission": "studio:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "nodeId": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "nodeId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Document Nodes Regenerate.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example", "nodeId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/example/document/nodes/example/regenerate", "body": { "siteId": "example", "nodeId": "example" } }, "effects": "May change state through POST /api/studio/sites/{siteId}/document/nodes/{nodeId}/regenerate. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/document/nodes/*/regenerate", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.publish", "title": "Sites Publish", "description": "Call POST /studio/sites/{siteId}/publish.", "method": "POST", "path": "/api/studio/sites/{siteId}/publish", "permission": "publish:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Publish TopoloWeb site", "type": "object", "description": "Publish one quality-approved site as a new immutable active version.", "properties": { "siteId": { "type": "string", "description": "Site identifier returned by sites.build or site discovery.", "minLength": 1 }, "label": { "type": "string", "description": "Optional human-readable version label.", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "description": "Published site, immutable version, quality evidence, and verification URLs.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "version": { "$ref": "#/$defs/siteVersion" }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "urls": { "$ref": "#/$defs/siteUrls" } }, "required": [ "site", "version", "qualityReport", "urls" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/applications/web#publish-and-recover", "resource": { "kind": "site", "idPath": "site.id", "versionPath": "version.id" }, "effects": [ "Creates and activates one immutable published version." ], "errors": [ { "status": 422, "code": "publish_blocked", "recovery": "Resolve every error returned by sites.publish.preflight." } ], "verify": [ "Open urls.publicUrl and confirm the returned version.id is active." ], "rollbackActionId": "app_topolo_web.sites.versions.restore", "nextActionIds": [ "app_topolo_web.sites.versions.list" ], "examples": [ { "title": "Publish a quality-approved site", "description": "Use the site id returned by sites.build after sites.publish.preflight reports canPublish=true.", "input": { "siteId": "site_example", "label": "Launch" } } ] }, "authorizationMode": "static", "documentation": { "example_input": { "siteId": "site_example", "label": "Launch" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/site_example/publish", "body": { "siteId": "site_example", "label": "Launch" } }, "effects": "Creates and activates one immutable published version.", "verification": [ "Open urls.publicUrl and confirm the returned version.id is active." ], "recovery": [ "422 publish_blocked: Resolve every error returned by sites.publish.preflight." ], "docs_url": "https://docs.topolo.app/applications/web#publish-and-recover", "resource": { "kind": "site", "idPath": "site.id", "versionPath": "version.id" }, "next_action_ids": [ "app_topolo_web.sites.versions.list" ], "rollback_action_id": "app_topolo_web.sites.versions.restore" }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/publish", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.domains.create", "title": "Sites Domains Create", "description": "Call POST /studio/sites/{siteId}/domains.", "method": "POST", "path": "/api/studio/sites/{siteId}/domains", "permission": "domains:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "hostname": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "platform", "custom" ] }, "isPrimary": { "type": "boolean" } }, "required": [ "siteId", "hostname", "kind" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Domains Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example", "hostname": "example", "kind": "platform" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/example/domains", "body": { "siteId": "example", "hostname": "example", "kind": "platform" } }, "effects": "May change state through POST /api/studio/sites/{siteId}/domains. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/domains", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.domains.verify", "title": "Sites Domains Verify", "description": "Call POST /studio/sites/{siteId}/domains/{domainId}/verify.", "method": "POST", "path": "/api/studio/sites/{siteId}/domains/{domainId}/verify", "permission": "domains:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "domainId": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "domainId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Domains Verify.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example", "domainId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/example/domains/example/verify", "body": { "siteId": "example", "domainId": "example" } }, "effects": "May change state through POST /api/studio/sites/{siteId}/domains/{domainId}/verify. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/domains/*/verify", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.domains.delete", "title": "Delete site domain", "description": "Delete one domain from a site.", "permission": "domains:write", "method": "DELETE", "path": "/api/studio/sites/{siteId}/domains/{domainId}", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "domainId": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "domainId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": true, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example", "domainId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "DELETE", "path": "/api/studio/sites/example/domains/example", "body": null }, "effects": "May change state through DELETE /api/studio/sites/{siteId}/domains/{domainId}. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "DELETE /api/studio/sites/*/domains/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.assets.create", "title": "Sites Assets Create", "description": "Call POST /studio/sites/{siteId}/assets.", "method": "POST", "path": "/api/studio/sites/{siteId}/assets", "permission": "assets:write", "requiresConfirmation": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "favicon", "logo", "hero", "gallery", "proof", "poster", "video" ] }, "url": { "type": "string", "minLength": 1 }, "alt": { "type": "string" } }, "required": [ "siteId", "label", "kind", "url", "alt" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Assets Create.", "additionalProperties": true }, "readOnly": false, "destructive": false, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example", "label": "example", "kind": "favicon", "url": "https://example.com", "alt": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/example/assets", "body": { "siteId": "example", "label": "example", "kind": "favicon", "url": "https://example.com", "alt": "example" } }, "effects": "May change state through POST /api/studio/sites/{siteId}/assets. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/assets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.assets.upload", "title": "Upload site asset", "description": "Upload a base64-encoded image or video asset to one site.", "permission": "assets:write", "method": "POST", "path": "/api/studio/sites/{siteId}/assets/upload", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "favicon", "logo", "hero", "gallery", "proof", "poster", "video" ] }, "fileName": { "type": "string", "minLength": 1 }, "contentType": { "type": "string", "minLength": 1 }, "dataBase64": { "type": "string", "minLength": 1 }, "alt": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "label", "kind", "fileName", "contentType", "dataBase64", "alt" ], "additionalProperties": false }, "agentContract": { "upload": { "profile": "inline-base64", "contentField": "dataBase64", "contentTypeField": "contentType", "fileNameField": "fileName", "maxBytes": 16777216, "acceptedContentTypes": [ "image/jpeg", "image/png", "image/webp", "image/gif", "image/svg+xml", "video/mp4", "video/webm", "video/ogg" ] } }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example", "label": "example", "kind": "favicon", "fileName": "example", "contentType": "example", "dataBase64": "example", "alt": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/example/assets/upload", "body": { "siteId": "example", "label": "example", "kind": "favicon", "fileName": "example", "contentType": "example", "dataBase64": "example", "alt": "example" } }, "effects": "May change state through POST /api/studio/sites/{siteId}/assets/upload. Inspect the plan and honor the published confirmation policy.", "verification": [ "Check the structured action result.", "Read the affected resource back through the corresponding get or list action." ], "recovery": [ "Do not retry an ambiguous mutation until a read confirms whether it applied.", "Use a published inverse, update, archive, or delete action only after inspecting its contract." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/assets/upload", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "widget.get", "title": "Get widget summary", "description": "Get the TopoloOne widget summary for this service.", "method": "GET", "path": "/api/widget", "permission": "runtime:read", "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", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --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": "sites.list", "title": "Sites List", "description": "Call GET /studio/sites.", "method": "GET", "path": "/api/studio/sites", "permission": "studio:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": {}, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/studio/sites", "body": null }, "effects": "Reads state through GET /api/studio/sites without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/studio/sites", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.get", "title": "Sites Get", "description": "Call GET /studio/sites/{siteId}.", "method": "GET", "path": "/api/studio/sites/{siteId}", "permission": "studio:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/studio/sites/example", "body": null }, "effects": "Reads state through GET /api/studio/sites/{siteId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/studio/sites/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.quality.get", "title": "Get site quality", "description": "Get deterministic content and launch-quality findings for one site.", "permission": "studio:read", "method": "GET", "path": "/api/studio/sites/{siteId}/quality", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$ref": "#/$defs/qualityReport", "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/studio/sites/example/quality", "body": null }, "effects": "Reads state through GET /api/studio/sites/{siteId}/quality without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/studio/sites/*/quality", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.preview.get", "title": "Get site preview", "description": "Get stable draft-preview and public URLs plus required responsive QA viewports.", "permission": "studio:read", "method": "GET", "path": "/api/studio/sites/{siteId}/preview", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "description": "Stable draft preview coordinates.", "properties": { "siteId": { "type": "string", "description": "Site identifier.", "minLength": 1 }, "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public URL used after publication.", "format": "uri" }, "viewports": { "type": "array", "description": "Required responsive QA viewports.", "items": { "type": "object", "description": "One required QA viewport.", "properties": { "id": { "type": "string", "description": "Viewport identifier.", "enum": [ "mobile", "tablet", "desktop", "4k" ] }, "width": { "type": "integer", "description": "Viewport width in CSS pixels.", "minimum": 1 }, "description": { "type": "string", "description": "What this viewport verifies.", "minLength": 1 } }, "required": [ "id", "width", "description" ], "additionalProperties": false } } }, "required": [ "siteId", "previewUrl", "publicUrl", "viewports" ], "additionalProperties": false }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/studio/sites/example/preview", "body": null }, "effects": "Reads state through GET /api/studio/sites/{siteId}/preview without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/studio/sites/*/preview", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.publish.preflight", "title": "Get site publish preflight", "description": "Check publish readiness, verification URLs, responsive viewports, and rollback action without changing the site.", "permission": "studio:read", "method": "GET", "path": "/api/studio/sites/{siteId}/publish-preflight", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "description": "Non-mutating publish readiness result.", "properties": { "canPublish": { "type": "boolean", "description": "Whether deterministic launch gates allow publishing." }, "siteId": { "type": "string", "description": "Site identifier.", "minLength": 1 }, "previewUrl": { "type": "string", "description": "Draft preview URL to verify visually.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public URL that publishing will activate.", "format": "uri" }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "requiredViewports": { "type": "array", "description": "Viewport widths that must be visually verified.", "items": { "type": "integer", "description": "Viewport width in CSS pixels.", "minimum": 1 } }, "rollbackActionId": { "type": "string", "description": "Action used to restore a previous published version.", "const": "app_topolo_web.sites.versions.restore" } }, "required": [ "canPublish", "siteId", "previewUrl", "publicUrl", "qualityReport", "requiredViewports", "rollbackActionId" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/studio/sites/example/publish-preflight", "body": null }, "effects": "Reads state through GET /api/studio/sites/{siteId}/publish-preflight without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/studio/sites/*/publish-preflight", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.collections.list", "title": "Sites Collections List", "description": "Call GET /studio/sites/{siteId}/collections.", "method": "GET", "path": "/api/studio/sites/{siteId}/collections", "permission": "studio:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Collections List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/studio/sites/example/collections", "body": null }, "effects": "Reads state through GET /api/studio/sites/{siteId}/collections without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/studio/sites/*/collections", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.code_snippets.list", "title": "Sites Code Snippets List", "description": "Call GET /studio/sites/{siteId}/code-snippets.", "method": "GET", "path": "/api/studio/sites/{siteId}/code-snippets", "permission": "settings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Code Snippets List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/studio/sites/example/code-snippets", "body": null }, "effects": "Reads state through GET /api/studio/sites/{siteId}/code-snippets without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/studio/sites/*/code-snippets", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.agent_sessions.list", "title": "Sites Agent Sessions List", "description": "Call GET /studio/sites/{siteId}/agent/sessions.", "method": "GET", "path": "/api/studio/sites/{siteId}/agent/sessions", "permission": "studio:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Agent Sessions List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/studio/sites/example/agent/sessions", "body": null }, "effects": "Reads state through GET /api/studio/sites/{siteId}/agent/sessions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/studio/sites/*/agent/sessions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.agent_sessions.get", "title": "Sites Agent Sessions Get", "description": "Call GET /studio/sites/{siteId}/agent/sessions/{sessionId}.", "method": "GET", "path": "/api/studio/sites/{siteId}/agent/sessions/{sessionId}", "permission": "studio:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "sessionId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Agent Sessions Get.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example", "sessionId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/studio/sites/example/agent/sessions/example", "body": null }, "effects": "Reads state through GET /api/studio/sites/{siteId}/agent/sessions/{sessionId} without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/studio/sites/*/agent/sessions/*", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.versions.list", "title": "Sites Versions List", "description": "Call GET /studio/sites/{siteId}/versions.", "method": "GET", "path": "/api/studio/sites/{siteId}/versions", "permission": "studio:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Versions List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/studio/sites/example/versions", "body": null }, "effects": "Reads state through GET /api/studio/sites/{siteId}/versions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/studio/sites/*/versions", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.versions.restore", "title": "Restore site version", "description": "Restore and publish one saved site version.", "permission": "publish:write", "method": "POST", "path": "/api/studio/sites/{siteId}/versions/{versionId}/restore", "readOnly": false, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Restore TopoloWeb site version", "type": "object", "description": "Restore one immutable version belonging to the selected site and activate it as a new version.", "properties": { "siteId": { "type": "string", "description": "Site identifier returned by site discovery.", "minLength": 1 }, "versionId": { "type": "string", "description": "Version identifier returned by sites.versions.list for the same site.", "minLength": 1 } }, "required": [ "siteId", "versionId" ], "additionalProperties": false }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "description": "Published site, immutable version, quality evidence, and verification URLs.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "version": { "$ref": "#/$defs/siteVersion" }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "urls": { "$ref": "#/$defs/siteUrls" } }, "required": [ "site", "version", "qualityReport", "urls" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } }, "target": "api", "destructive": false, "requiresConfirmation": true, "agentAccess": "confirm", "agentContract": { "docsUrl": "https://docs.topolo.app/applications/web#publish-and-recover", "resource": { "kind": "site", "idPath": "site.id", "versionPath": "version.id" }, "effects": [ "Creates and activates a new immutable version from the selected snapshot." ], "errors": [ { "status": 404, "code": "version_not_found", "recovery": "Call sites.versions.list and select a version belonging to the same site." } ], "verify": [ "Open urls.publicUrl and confirm version.id is the new active version." ], "nextActionIds": [ "app_topolo_web.sites.versions.list" ], "examples": [ { "title": "Restore a version from the same site", "description": "Resolve versionId through sites.versions.list before planning this action.", "input": { "siteId": "site_example", "versionId": "version_example" } } ] }, "authorizationMode": "static", "documentation": { "example_input": { "siteId": "site_example", "versionId": "version_example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --confirm --json" ], "http_example": { "method": "POST", "path": "/api/studio/sites/site_example/versions/version_example/restore", "body": { "siteId": "site_example", "versionId": "version_example" } }, "effects": "Creates and activates a new immutable version from the selected snapshot.", "verification": [ "Open urls.publicUrl and confirm version.id is the new active version." ], "recovery": [ "404 version_not_found: Call sites.versions.list and select a version belonging to the same site." ], "docs_url": "https://docs.topolo.app/applications/web#publish-and-recover", "resource": { "kind": "site", "idPath": "site.id", "versionPath": "version.id" }, "next_action_ids": [ "app_topolo_web.sites.versions.list" ], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "POST /api/studio/sites/*/versions/*/restore", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.domains.list", "title": "Sites Domains List", "description": "Call GET /studio/sites/{siteId}/domains.", "method": "GET", "path": "/api/studio/sites/{siteId}/domains", "permission": "settings:read", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "target": "api", "outputSchema": { "type": "object", "description": "Response returned by Sites Domains List.", "additionalProperties": true }, "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/studio/sites/example/domains", "body": null }, "effects": "Reads state through GET /api/studio/sites/{siteId}/domains without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/studio/sites/*/domains", "evidence": "Matched to a served route extracted from canonical staging source." } }, { "name": "sites.submissions.list", "title": "List site submissions", "description": "List form submissions captured by one site.", "permission": "studio:read", "method": "GET", "path": "/api/studio/sites/{siteId}/submissions", "readOnly": true, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false }, "outputSchema": { "type": "object", "additionalProperties": true }, "target": "api", "destructive": false, "requiresConfirmation": false, "agentAccess": "auto", "authorizationMode": "static", "documentation": { "example_input": { "siteId": "example" }, "cli_example": [ "topolo actions --service topolo-web --json", "topolo actions get --json", "topolo actions validate --data @payload.json --json", "topolo actions plan --data @payload.json --json", "topolo actions call --data @payload.json --json" ], "http_example": { "method": "GET", "path": "/api/studio/sites/example/submissions", "body": null }, "effects": "Reads state through GET /api/studio/sites/{siteId}/submissions without a declared mutation.", "verification": [ "Check the structured action result and pagination or resource identifiers before using it downstream." ], "recovery": [ "Correct identity, resource context, permission, or input validation failures, then retry the read." ], "docs_url": null, "resource": null, "next_action_ids": [], "rollback_action_id": null }, "implementation": { "status": "implemented", "route_key": "GET /api/studio/sites/*/submissions", "evidence": "Matched to a served route extracted from canonical staging source." } } ], "action_coverage": { "status": "ok", "served_routes": 48, "matched_actions": 44, "declared_unserved_actions": [], "coverage_excluded_actions": [], "uncatalogued_routes": [], "ignored_routes": 4, "configured_exclusions": 2, "configuration_findings": [], "notes": [ "missing/compiled target runtime — no source found" ] }, "runtime_contract_audit": { "status": "verified", "actions": 44, "contracts": 44, "contract_module": "topolo.action-contracts.mjs", "validator_sources": [ "apps/api/src/index.ts" ], "authorization_sources": [ "apps/api/src/index.ts" ], "findings": [] } } ], "mobile_contracts": [ { "source_path": "apps/TopoloWeb/topolo.mobile-experience.json", "contract": { "version": "2026-06-29", "status": "approved", "mode": "native_capability", "appId": "app_topolo_web", "localizationNamespace": "web", "permissions": [ "studio:read", "studio:write" ], "offlinePolicy": "read_through_cache", "fallbackPath": "/sites", "auth": { "audience": "topoloweb", "scopes": [ "studio:read", "studio:write" ] }, "routes": [ { "path": "/sites", "apiPath": "/api/studio/sites", "title": "Sites", "titleKey": "web.mobile.routes.sites.title", "template": "record.list", "dataSource": "web.sites.list", "detailRoute": "/sites/:id", "actions": [ { "id": "web.sites.create", "title": "Create site", "type": "record.create", "permission": "studio:write", "method": "POST", "path": "/api/studio/sites", "fields": [ { "key": "name", "label": "Name", "type": "text", "required": true }, { "key": "slug", "label": "Slug", "type": "text", "required": true }, { "key": "description", "label": "Description", "type": "textarea" } ], "titleKey": "web.mobile.actions.sites.create.title" }, { "id": "web.sites.update", "title": "Update site", "type": "record.update", "permission": "studio:write", "method": "PUT", "path": "/api/studio/sites/:id", "fields": [ { "key": "name", "label": "Name", "type": "text" }, { "key": "slug", "label": "Slug", "type": "text" }, { "key": "description", "label": "Description", "type": "textarea" } ], "titleKey": "web.mobile.actions.sites.update.title" }, { "id": "web.sites.delete", "title": "Delete site", "type": "record.delete", "permission": "studio:write", "method": "DELETE", "path": "/api/studio/sites/:id", "titleKey": "web.mobile.actions.sites.delete.title" } ] }, { "path": "/sites/:id", "apiPath": "/api/studio/sites/:id", "title": "Site", "titleKey": "web.mobile.routes.sites.title", "template": "record.detail", "dataSource": "web.sites.detail" } ] } } ], "package_manifests": [], "deployment_configs": [ { "source_path": "apps/TopoloWeb/apps/runtime/wrangler.jsonc", "name": "topolo-web-runtime", "main": "@astrojs/cloudflare/entrypoints/server", "compatibility_date": "2026-04-10", "observability_enabled": true, "environments": [ "development", "production", "staging" ], "variable_names": [ "PUBLIC_TOPOLOWEB_API_URL", "PUBLIC_TOPOLOWEB_TURNSTILE_SITE_KEY" ], "routes": [], "cron_triggers": [], "bindings": [ { "kind": "kv", "binding": "SESSION", "target": null }, { "kind": "service", "binding": "API", "target": null } ] } ], "source_signals": { "api_routes": [ { "method": "ALL", "path": "/__seed/*", "source_path": "apps/TopoloWeb/apps/api/src/index.ts" }, { "method": "GET", "path": "/health", "source_path": "apps/TopoloWeb/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/assets/:assetId", "source_path": "apps/TopoloWeb/apps/api/src/index.ts" }, { "method": "GET", "path": "/api/widget", "source_path": "apps/TopoloWeb/apps/api/src/index.ts" }, { "method": "ALL", "path": "/", "source_path": "apps/TopoloWeb/apps/api/src/index.ts" } ], "ui_routes": [], "test_cases": [], "database_tables": [] }, "documentation": { "declared_paths": [ "applications/web", "internal/apps/topolo-web", "internal/platform/application-entry-and-admission" ], "present_paths": [ "applications/web", "internal/apps/topolo-web", "internal/platform/application-entry-and-admission" ], "missing_paths": [], "human_reference": "/systems/topolo-web", "machine_reference": "/machine/systems/topolo-web.json", "action_examples": 44, "action_schemas": 44 }, "source_findings": [] } } }