Developers

CalDAV Integration Both

TapTidy exposes a CalDAV server that lets standards-compliant clients sync tasks as VTODO components. This guide covers the protocol details for developers building integrations or debugging client connections.

★

Pro Feature: CalDAV access requires a TapTidy Pro subscription and an App Password for authentication.

Server Endpoints

Path	Purpose
`/.well-known/caldav`	RFC 6764 service discovery redirect
`/caldav/`	CalDAV root — principal discovery
`/caldav/<userId>/`	User principal and home set
`/caldav/<userId>/tasks/`	Task collection (VTODO calendar)
`/caldav/<userId>/tasks/<taskId>.ics`	Individual task resource

Authentication

CalDAV clients authenticate with HTTP Basic Auth using the user's email and an App Password:

Authorization: Basic base64(email:<appPasswordId>.<secret>)

Generate App Passwords under Settings → Developer. The password needs at least tasks:read scope for read access and tasks:write for mutations.

Discovery Flow

Standards-compliant clients (Apple Reminders, DAVx⁵, Thunderbird) follow this sequence:

PROPFIND /.well-known/caldav — redirects to /caldav/.
PROPFIND /caldav/ — returns current-user-principal.
PROPFIND /caldav/<userId>/ — returns calendar-home-set.
PROPFIND /caldav/<userId>/tasks/ — enumerates the task collection.

Supported Methods

Method	Purpose
`PROPFIND`	Principal, home set, and collection property discovery
`REPORT`	RFC 6578 sync-collection with hybrid sync tokens
`GET`	Fetch a task as an iCalendar `.ics` file
`PUT`	Create or update a task from a `VTODO` payload
`DELETE`	Delete a task
`MKCALENDAR`	WebDAV compliance (collection already exists)
`OPTIONS`	Returns supported methods and DAV compliance classes

Sync Tokens

The server uses hybrid sync tokens in the format urn:taptidy:sync:<updatedAtMillis>-<deleteSeq>. Clients that support RFC 6578 sync-collection reports can pass a previously received sync token to receive only changes since that point, reducing bandwidth and latency.

ETags & Conditional Updates

Each task resource returns an ETag header derived from the task ID and last-modified timestamp. Clients can send If-Match on PUT or DELETE to prevent overwriting concurrent changes. A mismatched ETag returns 412 Precondition Failed.

Task Mapping

TapTidy tasks map to iCalendar VTODO components. Key field mappings:

TapTidy field	iCalendar property
`title`	`SUMMARY`
`description`	`DESCRIPTION`
`dueDate`	`DUE`
`completedAt`	`COMPLETED` + `STATUS:COMPLETED`
`priority`	`PRIORITY` (1–9 scale)

Outbound CalDAV Sync

TapTidy can also act as a CalDAV client, syncing tasks from an external CalDAV server. Users provide their server URL, username, and password under Settings → Integrations → CalDAV. Credentials are encrypted at rest (AES-256-GCM) and stored via the secrets provider. The sync engine runs synchronously (no async runtime) using the Rust core's ureq-based client.

Troubleshooting

Common issues and solutions are documented in CalDAV Troubleshooting. For Home Assistant entity integration, see Home Assistant.