How can we help you?

Advanced documentation search

PUT /calendars/:calendarUuid/:eventFile

Product: FeraCalendar Topic: API Versions: Applies to all documented versions Current
Written by user
Updated

Audience: Application developers
Editorial status: Published — Source Validated
Product: FeraCalendar
Classification: partner

PUT /caldav/calendars/{calendarUuid}/{path}

Overview

Authenticated conditional event write implemented at src/caldav/router.js:42 (controller.putEvent). The adapter validates one VEVENT, requires its UID to match the UUID .ics filename, checks write capability and If-Match, then creates or updates the FeraCal event.

Authentication and access

Security scheme: basicAuth

Control Contract
Authentication authenticated
Authorization HTTP Basic credentials are verified by FeraAuth and the resolved principal must have write capability for the selected calendar context.
Licensing The adapter has no separate local product-license middleware; it relies on FeraAuth credential verification and FeraCal calendar-access resolution for the effective instance.
Instance Context Principal and instance routes supply an instance UUID. Calendar routes first resolve the calendar UUID to its owner instance, then verify credentials in that effective context.
Ownership The verified FeraAuth user is resolved to a FeraCal person and calendar role; collection and event access is constrained to calendars for which that principal has the required capability.

Parameters

Name Location Type Required Description
calendarUuid path string (uuid) Yes FeraCal calendarUuid UUID used for CalDAV discovery and authorization.
path path string Yes Event resource filename. The basename must be a UUID and the extension must be .ics.
If-Match header string No Current event ETag used for optimistic conditional mutation. Omission performs an unconditional write or delete.

Request body

RFC 5545 iCalendar containing one VEVENT whose UID matches the event resource filename.

text/calendar

Schema: string

BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VEVENT
UID:715c9ebb-0470-11f1-a928-0ed2cd1b87df
DTSTART:20260901T130000Z
DTEND:20260901T140000Z
SUMMARY:Client consultation
END:VEVENT
END:VCALENDAR

Example request

cURL

curl --request PUT \ \
  --url 'https://caldav.feradel.com/caldav/calendars/715c9ebb-0470-11f1-a928-0ed2cd1b87df/715c9ebb-0470-11f1-a928-0ed2cd1b87df.ics' \
  --user '$FERA_CALDAV_USERNAME:$FERA_CALDAV_PASSWORD' \
  --header 'If-Match: "event-etag"' \
  --header 'content-type: text/calendar' \
  --data 'BEGIN:VCALENDAR\r\nVERSION:2.0\r\nBEGIN:VEVENT\r\nUID:715c9ebb-0470-11f1-a928-0ed2cd1b87df\r\nDTSTART:20260901T130000Z\r\nDTEND:20260901T140000Z\r\nSUMMARY:Client consultation\r\nEND:VEVENT\r\nEND:VCALENDAR\r\n'

Responses

201 A new VEVENT was created.

Header Description
ETag Entity tag of the created event.

204 An existing VEVENT was updated without a response body.

Header Description
ETag Entity tag after the update.

400 The filename, iCalendar document, VEVENT, or backend validation failed.

Content type: application/json; schema: CalDavError

{
    "success": false,
    "error": {
        "message": "Invalid iCalendar event"
    }
}

401 Basic credentials are missing or rejected.

Content type: application/json; schema: CalDavError

{
    "success": false,
    "error": {
        "message": "CalDAV credentials are required"
    }
}

403 The verified principal lacks calendar write access.

Content type: application/json; schema: CalDavError

{
    "success": false,
    "error": {
        "message": "Calendar write access denied"
    }
}

409 The VEVENT UID differs from the .ics resource UUID.

Content type: application/json; schema: CalDavError

{
    "success": false,
    "error": {
        "message": "VEVENT UID must match resource name"
    }
}

412 If-Match does not equal the current event ETag.

Content type: application/json; schema: CalDavError

{
    "success": false,
    "error": {
        "message": "ETag precondition failed"
    }
}

500 The calendar write dependency failed.

Content type: application/json; schema: CalDavError

{
    "success": false,
    "error": {
        "message": "Internal server error"
    }
}

Status and retry matrix

Status Condition Retryable Developer action
201 A new VEVENT was created. No Continue with the DAV, XML, iCalendar, ETag, or empty-body result described for this status.
204 An existing VEVENT was updated without a response body. No Continue with the DAV, XML, iCalendar, ETag, or empty-body result described for this status.
400 The filename, iCalendar document, VEVENT, or backend validation failed. No Correct credentials, capability, resource name, XML/iCalendar content, UID, or ETag before retrying.
401 Basic credentials are missing or rejected. No Correct credentials, capability, resource name, XML/iCalendar content, UID, or ETag before retrying.
403 The verified principal lacks calendar write access. No Correct credentials, capability, resource name, XML/iCalendar content, UID, or ETag before retrying.
409 The VEVENT UID differs from the .ics resource UUID. No Correct credentials, capability, resource name, XML/iCalendar content, UID, or ETag before retrying.
412 If-Match does not equal the current event ETag. No Correct credentials, capability, resource name, XML/iCalendar content, UID, or ETag before retrying.
500 The calendar write dependency failed. Yes Correct credentials, capability, resource name, XML/iCalendar content, UID, or ETag before retrying.

Related operations and events

  • Operation caldav_get_28
  • Operation caldav_delete_30

Source trace

Repository: feradelinc/feradel.calendar.caldav
Route: src/caldav/router.js
Handler: controller.putEvent
Line: 42
Contract: OpenAPI 3.1, source-traced and publication-validated.