CalDAV & CardDAV¶
oAI-Web integrates with CalDAV (calendars) and CardDAV (contacts) servers. Both are configured per-user — there is no system-wide fallback.
Setup¶
Go to Settings → CalDAV/CardDAV (user settings) and enter:
- CalDAV URL — e.g.
https://mail.example.com(host only; principal path is auto-discovered) - Username — your email address or CalDAV username
- Password — account or app-specific password
- Calendar name (optional) — filter to a specific calendar by display name
Principal discovery¶
The caldav tool auto-discovers your calendar URL using the SOGo principal path:
This works with Mailcow/SOGo. For other CalDAV servers (e.g. Nextcloud, Radicale), you may need to set the full CalDAV URL in the user settings.
Calendar operations¶
| Operation | What it does | Confirmation required |
|---|---|---|
list_events |
List events in a date range | No |
get_event |
Get full event details by UID | No |
create_event |
Create a new calendar event | Yes |
update_event |
Update an existing event | Yes |
delete_event |
Delete an event | Yes |
All datetimes are stored in UTC internally and displayed in the configured timezone (default: Europe/Oslo).
Maximum events returned per list_events call: 100.
Contacts (CardDAV)¶
Contacts use CardDAV with direct httpx HTTP calls (REPORT/PUT/DELETE). The caldav Python library does not support AddressBooks, hence the custom implementation.
| Operation | What it does |
|---|---|
list_contacts |
List all contacts |
search_contacts |
Search by name or email |
create_contact |
Create a new vCard contact |
update_contact |
Update an existing contact |
Implementation notes¶
Why per-user only?
Calendar data is personal. Multiple users should each connect to their own calendar, not share one. There is no admin "system CalDAV" — every user who wants calendar access must configure it themselves.
Why httpx for CardDAV?
The caldav==2.2.6 library has no AddressBook support. Rather than switch CalDAV libraries entirely (breaking calendar support), CardDAV uses direct HTTP (REPORT for discovery/search, PUT for create/update, DELETE for delete). This is documented in project_caldav_carddav.md in the project memory.
Bare hostname handling
If you enter a hostname without a scheme (e.g. mail.example.com), the tool automatically prepends https://.