List external calendars — Calendar

Discover external calendar IDs, connection state and sync history.

Action: app_topolo_calendar.external_calendars.list · GET /api/admin/external-calendars

Declared permission: app_topolo_calendar.availability:read. For authorized Calendar users; permissions and resource access still apply.

Before you start

Use the current credential to confirm the production organization and inspect this exact action before preparing a call.
Declared permission: app_topolo_calendar.availability:read. Permission discovery is not a grant.
Discover the authorized Calendar workspace and pass it as resourceType=workspace/resourceId separately from this action input. Calendar records and IDs are scoped to the selected host/workspace.

Inputs and field meanings

No action input fields. Supply the empty JSON object {}; keep resource context separate.

Worked request and response

Source-reviewed illustration only. Nothing below was executed; all identifiers, counts, states, credentials and URLs are synthetic. Replace identifiers through discovery before any separately authorized call.

Resource context: workspace; it is not an extra action input field.

Illustrative action input:

{}

Illustrative HTTP 200 source response:

{
  "externalCalendars": [
    {
      "id": "cal_example",
      "hostId": "hst_example",
      "provider": "manual",
      "accountEmail": "host@example.com",
      "displayName": "Example busy calendar",
      "providerCalendarId": null,
      "nexusConnectionId": null,
      "connectionStatus": null,
      "connectionStatusReason": null,
      "lastSyncedAt": null,
      "status": "active",
      "syncCursor": null,
      "lastError": null,
      "createdAt": "2026-11-01T00:00:00.000Z",
      "updatedAt": "2026-11-01T00:00:00.000Z"
    }
  ]
}

This manual record is registered but never synced: lastSyncedAt is null. For provider-backed records, connectionStatus is hydrated from Nexus and may differ from sync status. Neither active label alone proves useful busy time was imported.

The illustrative response passes the declared structural schema. This establishes only schema compatibility, not deployed shape, values, authorization or business outcome.

Effects and verification

Reads the host’s Calendar projections and hydrates provider connection metadata through Nexus.

Match the discovered ID/provider/connection state and lastSyncedAt before selecting a sync or disconnect action.

Refusals and recovery

Selected source refusals are listed below; runtime middleware can return additional structured errors.

HTTP	Error	Supported response
403	`forbidden`	Reconcile the declared permission, organization and verified resource grant with the legitimate access owner; do not switch context to bypass a refusal.
404	`no_host`	Read host.get; if it returns host:null, create the intended workspace host through host.update before retrying.

Recovery: This read does not mutate Calendar records. Correct the selected context or request fields before another authorized read.

app_topolo_calendar.external_calendars.create: Register an ICS/manual calendar without importing busy time yet.
app_topolo_calendar.external_calendars.sync: Replace an external calendar’s imported busy-time snapshot.
app_topolo_calendar.external_calendars.oauth.start: Begin a human Google/Microsoft calendar authorization.

Declared schemas and provenance

The hidden action guide carries these exact current declared schemas. They are not rewritten to make the illustrations pass.

Input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Output schema:

{
  "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"
}

Source: TopoloCalendar@b378ceb73800ee1d1e6c4ff6f0b4179918cf632c, apps/api/src/routes/admin-external-calendars.ts. Current catalog metadata and source were compared without executing the application.

Source-reviewed synthetic input/response; not captured or executed.
Source revision is not proof of current deployment, caller access, provider connection or notification delivery.
The illustrative response passes the declared structural schema. This establishes only schema compatibility, not deployed shape, values, authorization or business outcome.