Calendar (CalDAV)
CalDAV is the standard protocol for calendar access over HTTP. Nextcloud and ownCloud speak it, so do Yandex Calendar, iCloud, Fastmail and most corporate servers (SOGo, Zimbra, Radicale). The point for the platform is simple: one protocol instead of a dozen proprietary APIs — a workflow written against Nextcloud moves to another server by changing the address in the connection, not by rewriting the graph.
The unit of data in CalDAV is not “a row in a table” but a file: one event is an
iCalendar document (.ics) sitting at its own address inside a calendar collection.
Everything else on this page follows from that: an event has an href (its path) and an
etag (its version), and editing one means reading the file, changing it and writing it back.
What the connection stores
The connection is created in Settings → Integrations, kind CalDAV. The general mechanics of connections (secrets, permissions, port-beats-field) are covered in the integrations overview; this page covers only what is specific to calendars.
CalDAV
Connection form fields
Fills in the DAV endpoint address. Login and password stay your job.
At most providers this is an app password, not your account password.
Filled in — nodes can be left without a calendar address.
Only needed for sending invitations (scheduling).
The Provider picker fills in the base URL for you:
Nextcloud, ownCloud, Yandex Calendar, iCloud, Fastmail and
“Other (manual)”. For Nextcloud and ownCloud it only asks
for the host — the /remote.php/dav/ path is appended for you. A preset never touches the
login or the password: those are the one thing only you know.
Discovery mode answers “how do I find your calendars at this address”. “Automatic (PROPFIND)” is the standard route: ask the server for the current user, ask the user for their calendar home, ask the home for the calendars inside it. If your server answers off-spec there are two manual bypasses: name the calendar home, or name one specific calendar. The manual modes are not “stricter” — they simply skip the discovery steps your server does not implement.
Default calendar URL is worth filling in almost always. Nodes that need a collection address fall back to it when their own field is empty — otherwise the same long URL has to be pasted into every node of the graph.
There is currently no calendar picker in the form: collection addresses are obtained
with the List Calendars node, which returns the href and display name of every
calendar. Run it once, copy the href you want into the connection, and you can forget
about addresses afterwards.
Eleven nodes
Nine of them are ordinary graph steps carrying a calendar_store port. The tenth,
Calendar Tool, hands the same operations to an agent — same port, but no run input.
The eleventh, CalDAV Config, is not a graph step at all: it has neither a run input nor
a calendar_store port — it is what feeds that port.
| Node | What it does | Reads or writes |
|---|---|---|
| CalDAV Config | picks a saved connection and hands it to the other nodes | — |
| List Calendars | enumerates the account's collections: href, name, colour | read |
| Calendar Query | events (VEVENT) or tasks (VTODO) within a date range | read |
| Calendar Multiget | batch-fetches objects by a list of hrefs — up to 50 per call | read |
| Get Calendar Event | one object in full: the raw iCalendar plus parsed fields | read |
| Put Calendar Event | creates or replaces a whole object | write |
| Patch Calendar Event | changes individual fields of an existing event | write |
| Delete Calendar Event | removes the object | write |
| Calendar Free/Busy | busy intervals without any event content | read |
| Calendar Schedule | sends an invitation, a reply or a cancellation to attendees | write |
| Calendar Tool | the same operations, as tools for an AI agent | both |
They all take the connection the same way: either a CalDAV Config node wired by a data
edge into the calendar_store port, or a connection picked in the node’s own form. The port
beats the field. The port is also required: a graph with neither wired port nor filled
field gets a warning in the editor and is rejected at run and deploy — so the refusal
arrives before a paid run has already got halfway.
- Execute + Data
- Data
Reading: query first, addresses second
Working with CalDAV always follows the same order, and it is not obvious: ask for a date range first, take the addresses out of the answer, then fetch details by address.
-
List Calendars — once, to learn the
hrefof your collections. After that the address lives in the connection or in the node’s field. -
Calendar Query — with a collection address and a range (
fromandtoin ISO 8601). Returns a list of events with fields already parsed out:href,etag,uid,summary,dtstart,dtend, an all-day flag, time zone, recurrence rule, status. The range is capped at 366 days, the answer at 500 objects. -
Calendar Multiget or Get Calendar Event — when you need the full iCalendar rather than a summary. Multiget takes up to 50 addresses per call; the single-object node takes one. Both return an
icsfield with the source document.
An event’s address is whatever the query returned:
nodes.<query node>.output.events[0].href. You cannot and must not invent it — the server
assigns it.
Writing: href, etag and protection against someone else’s edit
There are three writing nodes, and they differ not in “power” but in what exactly they overwrite.
Put Calendar Event writes the whole object. An empty etag means “create” (or
“overwrite blindly”), a non-empty one means “write only if the event has not changed since”.
The event body is composed in one of two ways: from form fields (title, start, end, location,
description, attendees, recurrence rule) or from a raw iCalendar document when the field you
need is not in the form. A non-empty raw document always wins over the fields — that is
deliberate, for graphs saved earlier: they carry a raw body and know nothing about the
switch.
Patch Calendar Event is read-modify-write: the node fetches the current .ics itself,
substitutes the fields you filled in and writes it back. An empty field means “leave alone”,
not “erase”. That is how you move a meeting without losing the attendee list and the extra
data the form does not show.
Delete Calendar Event removes the object at an address; the etag is optional here too.
| Error code | When it arrives |
|---|---|
| NOT_FOUND | the address is gone: the event was deleted, or the href was copied wrong |
| ACCESS_DENIED | login or password rejected, or the account has no rights on the calendar |
| PRECONDITION_FAILED | stale etag — the event changed between the read and the write |
| CONFLICT | the server refused the write in the collection's current state |
| SIZE_LIMIT | the server's answer exceeds 8 MB |
| VALIDATION | a required field is empty, the range exceeds 366 days, more than 50 addresses |
| PROVIDER_ERROR | network or server: the only code that is retried automatically |
The difference between the last row and the rest is not cosmetic. A deterministic refusal (a
stale etag, an empty address) is pointless to repeat, and the engine does not repeat it; a
network failure is retried up to three times. Every code reaches the on_error branch as
error_code, so “the event was deleted” can be answered one way and “the server is down”
another. See Errors.
Free slots: busy time versus a query
Calendar Free/Busy answers “when is this person busy” without revealing with what.
The answer is a list of start/end intervals — no titles, attendees or descriptions. That
is precisely why the node exists separately from the query: on many servers free/busy is
readable by people who are not allowed to see calendar contents, so such an answer is safe
to send to a customer in a chat.
The node does not compute free windows — it returns busy ones. Inverting the intervals (take the working day, subtract the busy time, keep the chunks of the length you need) is currently your job: with a code node or with a model. There is no “suggest three slots” node.
- Execute + Data
- Data
Scheduling: invitations, and why they do not work everywhere
Calendar Schedule sends attendees an invitation (REQUEST), a reply to an invitation (REPLY) or a cancellation (CANCEL). Technically it writes an iCalendar document into a special collection — your account’s outbox — and the server itself mails the attendees.
Two hard conditions follow. First, the connection must have an Outbox URL. Second, the server must implement scheduling at all: iCloud and Google CalDAV do not. The platform knows this in advance and refuses up front, naming the provider, rather than firing the request and collecting an opaque 403 that reads like “wrong password”. Invitations through those services are sent with their own tooling, not over CalDAV.
The calendar as an agent tool
Calendar Tool is the same dozen operations, invoked by the model. This is the difference between a graph with a route per question and a conversation like “book me Tuesday afternoon”, where the model decides for itself: check busy time → pick a window → create the event → tell the human what happened.
- Execute + Data
- LLM
- Data
- Extension
- Execute + Data + Streaming
The node’s form lists twelve operations as checkboxes. Nine are on by default — everything except the three scheduling ones (invite, reply, cancel). The reason is the one above: without an outbox address, and on a provider that does not support scheduling, they fail on every call, and a tool that is guaranteed not to work is worse than an absent one — the model spends a round and a call budget slot learning that. Beyond that, scheduling tools that are ticked are still not shown to the model when the connection cannot support them. That is deliberate: let the model pick a path that can succeed.
Where this usually breaks
| Symptom | What happened | What to do |
|---|---|---|
| Check says "could not connect", the login is definitely right | the provider does not accept an account password over CalDAV | issue an app password in the provider's account settings; for Yandex, iCloud and most mail services this is mandatory |
| Check passes, 0 calendars found | the base URL does not point at a DAV endpoint (usually the web UI address was pasted) | take the address from the provider hint in the form or from the server's docs: for Nextcloud it is /remote.php/dav/ |
| Node fails with "calendar_url is required" | no collection address on the node and none on the connection | fill in the default calendar URL on the connection — once, for every node |
| The event landed three hours early | the time was passed without a time zone | write times with a Z or an offset (2026-07-01T10:00:00+03:00), or fill in the node's time-zone field |
| PRECONDITION_FAILED on the second write in a row | the second write got the etag from the first — which went stale the moment it succeeded | take the etag from the previous write's output, not from the read before it |
| VALIDATION: range exceeds 366 days | an "all time" query | split it into yearly ranges, or narrow the question |
| The run is rejected: a required port on the node is not wired | the tool's calendar_store port is empty and no connection is picked in its form | wire a CalDAV Config into the port or pick a connection in the form — the port is required, so this is a warning in the editor and an error at the run and deploy gate |
| The agent says the calendar is unavailable | a connection is picked but does not answer or does not fit | the tools are advertised to the model either way, and without a working connection the call returns it a textual error — read the tool-call text in the run rather than the agent's silence |
What next
Integrations: overview
How connections are stored and who may change them.
Agents and tools
The model loop, tool permissions, budgets.
Scheduled runs
So the calendar gets polled every morning by itself.
Errors and the on_error branch
Telling "event deleted" from "server down".
Templates and variables
Where the dates and addresses in node fields come from.
Node reference
Full schemas for all eleven calendar nodes.