Audience: Application developers
Editorial status: Published — Source Validated
Product: FeraCalendar
Classification: administrative
POST /api/v1/events
Overview
Implements controller.createOrUpdate in routes/api/v1/event/routes.js:8. The authenticated event boundary resolves the requested calendar and actor, enforces owner/editor/inviter rules, preserves recurrence, and joins attendee/resource invitation state without treating visibility as authorization by itself.
Deprecated compatibility paths
POST /api/events
Use the versioned canonical path for new integrations.
Authentication and access
Security scheme: authToken
| Control | Contract |
|---|---|
| Authentication | authenticated |
| Authorization | The route validates a JWT but does not invoke the available FeraAuth named-permission checker; VIEW/EDIT calendar, person, resource, and event grants are provisioned for owners but are not enforced by this router. Event create/delete applies creator or calendar owner/admin/editor checks where the service resolves that actor; invitation updates resolve their owner-scoped target. |
| Licensing | The global managed-product middleware requires the resolved FeraCal product instance to exist in Active lifecycle state before this route executes. |
| Instance Context | The instance header selects the FeraCal product instance. A trusted API-plane caller may replace it only with signed x-feradel-owner-instance, service, timestamp, and scope-signature headers. |
| Ownership | The command’s owner field defaults to the resolved product instance but, in the current implementation, a caller-supplied owner UUID is used without an equality check against that instance. This is a documented runtime isolation constraint; role checks described for sharing/events still apply. |
Parameters
No operation parameters.
Request body
Source-traced FeraCal JSON command.
application/json
Schema: CalMutation
{
"owner": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
"calendar": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
"name": "Client consultation",
"startsAt": "2026-09-01T13:00:00Z",
"endsAt": "2026-09-01T14:00:00Z",
"recurrence": null
}Example request
cURL
curl --request POST \ \
--url 'https://cal.feradel.com/api/v1/events' \
--header 'x-auth-token: $FERA_AUTH_TOKEN' \
--header 'content-type: application/json' \
--data '{"owner":"715c9ebb-0470-11f1-a928-0ed2cd1b87df","calendar":"715c9ebb-0470-11f1-a928-0ed2cd1b87df","name":"Client consultation","startsAt":"2026-09-01T13:00:00Z","endsAt":"2026-09-01T14:00:00Z","recurrence":null}'Responses
200 The source-traced FeraCal handler completed and returned its calendar, event, person, resource, access, invitation, or lifecycle representation.
Content type: application/json; schema: CalResult
{
"success": true,
"item": {
"uuid": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
"name": "Client consultation",
"calendarUuid": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
"startsAt": "2026-09-01T13:00:00Z",
"endsAt": "2026-09-01T14:00:00Z",
"attendees": [],
"resources": []
},
"items": [],
"uuid": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
"visibility": 7
}400 UUID, key, date range, fields, invite target, or command validation failed.
Content type: application/json; schema: CalError
{
"success": false,
"error": {
"message": "The calendar operation could not be completed.",
"category": "calendar",
"number": 800000
}
}401 The x-auth-token or lifecycle HMAC is invalid.
Content type: application/json; schema: CalError
{
"success": false,
"error": {
"message": "The calendar operation could not be completed.",
"category": "calendar",
"number": 800000
}
}403 Managed-product, owner, role, share/inviter, or lifecycle sender permission is missing.
Content type: application/json; schema: CalError
{
"success": false,
"error": {
"message": "The calendar operation could not be completed.",
"category": "calendar",
"number": 800000
}
}404 The owner-scoped calendar, event, person, resource, or invite target was not found.
Content type: application/json; schema: CalError
{
"success": false,
"error": {
"message": "The calendar operation could not be completed.",
"category": "calendar",
"number": 800000
}
}500 Persistence, invitation, lifecycle, or internal calendar processing failed.
Content type: application/json; schema: CalError
{
"success": false,
"error": {
"message": "The calendar operation could not be completed.",
"category": "calendar",
"number": 800000
}
}Status and retry matrix
| Status | Condition | Retryable | Developer action |
|---|---|---|---|
200 |
The source-traced FeraCal handler completed and returned its calendar, event, person, resource, access, invitation, or lifecycle representation. | No | Continue with the returned calendar state. |
400 |
UUID, key, date range, fields, invite target, or command validation failed. | No | Correct identity, scope, role, dates, invitation, resource, or dependency before retrying. |
401 |
The x-auth-token or lifecycle HMAC is invalid. | No | Correct identity, scope, role, dates, invitation, resource, or dependency before retrying. |
403 |
Managed-product, owner, role, share/inviter, or lifecycle sender permission is missing. | No | Correct identity, scope, role, dates, invitation, resource, or dependency before retrying. |
404 |
The owner-scoped calendar, event, person, resource, or invite target was not found. | No | Correct identity, scope, role, dates, invitation, resource, or dependency before retrying. |
500 |
Persistence, invitation, lifecycle, or internal calendar processing failed. | Yes | Correct identity, scope, role, dates, invitation, resource, or dependency before retrying. |
Related operations and events
- Operation
calendar_post_eventsInvite - Operation
calendar_get_eventsOKKeyVVisibility} - Operation
calendar_get_eventsIUuid} - Operation
calendar_delete_eventsIUuid}
Source trace
Repository: feradelinc/feradel.calendar.api
Route: routes/api/v1/event/routes.js
Handler: controller.createOrUpdate
Contract: OpenAPI 3.1, source-traced and publication-validated.