application · active
Calendar
Cloudflare-native scheduling and bookings application with public booking pages, availability, invitations, recurrence, and Google/Microsoft/CalDAV free/busy sync.
Documentation map
- Topolo Calendar — Public overview of the scheduling and booking application — shareable event types, availability, invitations, and calendar-safe booking lifecycle controls.
Authority and runtime
- System ID
topolo-calendar- App IDs
- app_topolo_calendar
- Owners
- platform-experience
- Repositories
- apps/TopoloCalendar
- Hosts
- https://calendar.topolo.app, https://calendar.stg.topolo.us
- Dependencies
- topolo-auth, topolo-chat, topolo-nexus, topolo-notify, applications-packages
Security and data ownership
- Risk tier
- high
- Tenant isolation
- organization_scoped
- Privacy classification
- restricted
- Storage
- d1, durable_object, external_provider
- Export and deletion
- implemented
- Enterprise ready
- no
Source-derived capability inventory
Source revisions: apps/TopoloCalendar@9e1b270431375af5b343e06176b64696084f5baf
Declared actions: 32 · API routes: 1 · UI routes: 21
{
"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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/widget",
"body": null
},
"effects": "Reads 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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/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 <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/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": []
}