CalDAV API

Ferro implements the CalDAV protocol (RFC 4791) for calendar access. Calendar data is stored as iCalendar (RFC 5545) resources.

Base URL

http://localhost:8080/dav/cal/

Calendar Discovery

Discover calendar home

curl -X OPTIONS http://localhost:8080/dav/cal \
  -H "Authorization: Bearer TOKEN"

Response includes DAV: calendar-access header.

List calendars

curl -X GET http://localhost:8080/dav/cal/ \
  -H "Authorization: Bearer TOKEN"

Get calendar properties

curl -X PROPFIND http://localhost:8080/dav/cal/default/ \
  -H "Authorization: Bearer TOKEN" \
  -H "Depth: 0" \
  -H "Content-Type: application/xml" \
  -d '<?xml version="1.0" encoding="utf-8"?>
       <D:propfind xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav">
         <D:prop>
           <D:displayname/>
           <C:calendar-color/>
           <C:getctag/>
         </D:prop>
       </D:propfind>'

Calendar Operations

Create a calendar

curl -X PUT http://localhost:8080/dav/cal/personal/ \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/xml" \
  -d '<?xml version="1.0" encoding="utf-8"?>
       <D:mkcol xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav">
         <D:set>
           <D:prop>
             <D:resourcetype>
               <D:collection/>
               <C:calendar/>
             </D:resourcetype>
             <D:displayname>Personal Calendar</D:displayname>
           </D:prop>
         </D:set>
       </D:mkcol>'

Delete a calendar

curl -X DELETE http://localhost:8080/dav/cal/personal/ \
  -H "Authorization: Bearer TOKEN"

Event Operations

Create an event

curl -X PUT http://localhost:8080/dav/cal/default/meeting.ics \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: text/calendar" \
  -d 'BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Ferro//EN
BEGIN:VEVENT
UID:meeting-1
DTSTART:20240101T100000Z
DTEND:20240101T110000Z
SUMMARY:Team Meeting
LOCATION:Conference Room A
END:VEVENT
END:VCALENDAR'

Get an event

curl http://localhost:8080/dav/cal/default/meeting.ics \
  -H "Authorization: Bearer TOKEN"

Delete an event

curl -X DELETE http://localhost:8080/dav/cal/default/meeting.ics \
  -H "Authorization: Bearer TOKEN"

Calendar Query (REPORT)

Query events by time range

curl -X REPORT http://localhost:8080/dav/cal/default/ \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/xml" \
  -d '<?xml version="1.0" encoding="utf-8"?>
       <C:calendar-query xmlns:C="urn:ietf:params:xml:ns:caldav">
         <D:prop xmlns:D="DAV:">
           <D:getetag/>
           <C:calendar-data/>
         </D:prop>
         <C:filter>
           <C:comp-filter name="VCALENDAR">
             <C:comp-filter name="VEVENT">
               <C:time-range start="20240101T000000Z" end="20240131T235959Z"/>
             </C:comp-filter>
           </C:comp-filter>
         </C:filter>
       </C:calendar-query>'

CTag Support

Calendars expose a getctag property that changes whenever any event in the calendar is modified. Use this for efficient synchronization:

curl -X PROPFIND http://localhost:8080/dav/cal/default/ \
  -H "Authorization: Bearer TOKEN" \
  -H "Depth: 0" \
  -H "Content-Type: application/xml" \
  -d '<?xml version="1.0" encoding="utf-8"?>
       <D:propfind xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav">
         <D:prop>
           <C:getctag/>
         </D:prop>
       </D:propfind>'

Compatible Clients

See the CalDAV Clients Guide for setup instructions.