calendar

Calendar workflows

Use an authorized calendar connection and fetch calls to the Notion tools API. This is an Apps alpha feature, not direct access to Google Calendar or Microsoft Graph. Read the tool reference before choosing an operation or writing its request body. It covers all 13 calendar tools.

Connection and access

Import connections from @notionhq/apps/workflow and add connections: [connections.calendar()] to the workflow. The declaration asks for a connection; it does not grant access. Finish calendar setup for the installed workflow, select its calendars and default calendar, and publish its configuration before running it. Use only the tools and calendars authorized for that connection.

Use the runtime's NOTION_API_TOKEN and NOTION_API_BASE_URL (default: https://api.notion.com). Never hard-code or log a token. Local checks do not need credentials. Live execution needs an eligible workflow token and a ready connection; a normal integration token or a personal agent's calendar access does not replace that setup.

If access is denied, check Apps calendar availability, published workflow setup, enabled tools, connection health, and calendar permissions. A workflow cannot pause for calendar write confirmation: writes that require confirmation are denied. Ask the owner to choose suitable permissions for the intended work; do not bypass confirmation or broaden access in code.

Request pattern

POST to /v1/tools/run with Notion-Version: 2026-03-11. The type and the sibling payload key must both be the exact snake_case tool name. Keep the payload's camelCase field names. Send only that tool's inputs, not Calendar service config, params, account credentials, or permission overrides.

This example lists the next 24 hours, not a local calendar day or week. Adapt the trigger and time zone to the requested job.

import { triggers } from "@notionhq/apps/triggers"
import { connections, createWorkflow } from "@notionhq/apps/workflow"

export default createWorkflow({
  name: "List upcoming calendar events",
  description: "Lists events in the next 24 hours.",
  triggers: [triggers.notionPageCreated()],
  connections: [connections.calendar()],
  handler: async (_event, context) => {
    const range = await context.step("Choose time range", () => {
      const now = Date.now()
      return {
        timeMin: new Date(now).toISOString(),
        timeMax: new Date(now + 24 * 60 * 60 * 1000).toISOString(),
        timeZone: "America/New_York",
      }
    })

    await context.step("List calendar events", async () => {
      const token = process.env.NOTION_API_TOKEN
      if (!token) throw new Error("NOTION_API_TOKEN is required.")
      const baseUrl =
        process.env.NOTION_API_BASE_URL || "https://api.notion.com"
      const response = await fetch(new URL("/v1/tools/run", baseUrl), {
        method: "POST",
        headers: {
          Authorization: `Bearer ${token}`,
          "Content-Type": "application/json",
          "Notion-Version": "2026-03-11",
        },
        body: JSON.stringify({
          type: "calendar_list_events",
          calendar_list_events: range,
        }),
      })
      if (!response.ok) {
        throw new Error(`Calendar lookup failed (HTTP ${response.status}).`)
      }
      const result: unknown = await response.json()
      if (
        !result ||
        typeof result !== "object" ||
        ("object" in result && result.object === "error") ||
        !("accounts" in result) ||
        !Array.isArray(result.accounts) ||
        !("errors" in result) ||
        !Array.isArray(result.errors)
      ) {
        throw new Error("Invalid calendar lookup response.")
      }
      if (result.errors.length > 0) {
        throw new Error(
          `Calendar lookup failed for ${result.errors.length} calendars.`
        )
      }
      return result
    })
  },
})