List bookings — Calendar

Find bookings within an explicit time window.

Action: app_topolo_calendar.bookings.list · GET /api/admin/bookings

Declared permission: app_topolo_calendar.bookings: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.bookings: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

Field	Presence	Declared constraint	Meaning
`windowStart`	required	string	Offset-aware beginning of the booking query or provider sync fetch window; use a meaningful window and pair with windowEnd.
`windowEnd`	required	string	Offset-aware end after windowStart. Manual/ICS sync does not use this field as a deletion boundary.

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:

{
  "windowStart": "2026-11-23T00:00:00+04:00",
  "windowEnd": "2026-11-24T00:00:00+04:00"
}

Illustrative HTTP 200 source response:

{
  "bookings": [
    {
      "id": "bkg_example",
      "hostId": "hst_example",
      "eventTypeId": "evt_example",
      "calendarUid": "bkg_example@calendar.topolo.app",
      "sequence": 1,
      "startAt": "2026-11-23T06:00:00.000Z",
      "endAt": "2026-11-23T06:30:00.000Z",
      "status": "confirmed",
      "inviteeName": "Example Invitee",
      "inviteeEmail": "invitee@example.com",
      "inviteeTimezone": "Asia/Dubai",
      "inviteeNotes": null,
      "meetingProvider": null,
      "meetingProviderRef": null,
      "createdAt": "2026-11-01T00:00:00.000Z",
      "updatedAt": "2026-11-01T00:00:00.000Z",
      "cancelledAt": null,
      "cancellationReason": null,
      "recurrenceSeriesId": null,
      "recurrenceInstanceStart": null
    }
  ]
}

The offset-aware request covers Monday 23 November in Asia/Dubai; the illustrated record is 10:00–10:30 local, stored as06:00–06:30UTC. This host-specific list is not every host or organization’s bookings.

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

This source query returns only pending or confirmed bookings that overlap the window; cancelled/completed records are excluded. Listed booking records are not attendee-hydrated. Use bookings.get for hydrated details.

Effects and verification

Reads this host’s bookings in the requested window.

Inspect booking IDs and statuses, then call bookings.get before modifying an individual booking.

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.
400	`invalid_window`	Supply valid offset-aware windowStart/windowEnd. Choose end after start even where schema alone does not enforce ordering.

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

app_topolo_calendar.host.get: Read the selected workspace host, including the unconfigured host:null state.
app_topolo_calendar.bookings.get: Read a booking and its related event type and delivery receipts.
app_topolo_calendar.bookings.create: Create a booking after discovering its event type and confirming the invitee/time.

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": {
    "windowStart": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "windowEnd": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    }
  },
  "required": [
    "windowStart",
    "windowEnd"
  ],
  "additionalProperties": false
}

Output schema:

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

Source: TopoloCalendar@b378ceb73800ee1d1e6c4ff6f0b4179918cf632c, apps/api/src/routes/admin-bookings.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.