Calendar
/api/calendar
Exposes calendars visible to the current user and stages calendar changes until they are validated and committed.
GET /api/calendar
Lists all calendars visible to the current user.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
fields |
query | string |
no | Comma-separated readable properties to include in the JSON response. |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
200 |
application/json |
array<CalendarRead> |
visible calendars ordered by their display name |
Example Request
# Request
GET /api/calendar HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
# Response
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"name": "string",
"displayName": "string",
"syncStatus": "string",
"externalSource": "string",
"providerCapabilities": "string"
}
]
POST /api/calendar
Creates an empty staged calendar. Request properties are applied before commit persists it.
Request Body
| Content Type | Schema | Required | Description |
|---|---|---|---|
application/json |
CalendarCreate |
yes | — |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
201 |
application/json |
CalendarRead |
new staged calendar |
Example Request
# Request
POST /api/calendar HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
Content-Type: application/json
{
"name": "string",
"externalSource": "string",
"color": "string",
"shares": [
{
"groupId": "5gpy3yy25nxakmr7i77pd7bhq",
"permission": "READ",
"userId": "f5f4d8brv2keh9izlp9j62e10"
}
],
"reminderDefault": true
}
# Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"name": "string",
"displayName": "string",
"syncStatus": "string",
"externalSource": "string",
"providerCapabilities": "string"
}
Common Error Responses
The status codes 400, 403, 404, 405, 406, 409, 413, 415, and 500 use the same ApiError JSON error format:
{
"status": 404,
"code": "route_not_found",
"message": "The requested API route does not exist.",
"details": []
}
Schemas
Request and response schemas used on this page.
CalendarRead
| Property | Type | Required | Description |
|---|---|---|---|
name |
string |
no |
Returns the optional local calendar name override. |
displayName |
string |
no |
Returns the effective name shown to users. |
syncStatus |
SyncStateView |
no |
Returns synchronization state for an external calendar. |
externalSource |
ExternalSourceView |
no |
Returns the external source without authentication data. |
providerCapabilities |
ProviderCapabilities |
no |
Returns capabilities of the currently configured calendar provider. |
permission |
string [READ, WRITE, ADMIN] |
no |
Returns the effective permission of the current user. |
id |
string |
no |
Unique calendar identifier. |
color |
string |
no |
Optional calendar color in CSS hexadecimal notation. |
shares |
array<ShareEntry> |
no |
Calendar shares that define user and group permissions. |
reminderDefault |
boolean |
no |
Whether new events use the default reminder setting. |
type |
string [PRIVATE, SHARED, EXTERNAL, API] |
no |
Calendar kind derived from its source and lifecycle. |
readOnly |
boolean |
no |
Whether the backing provider prevents modifications. |
remoteName |
string |
no |
Optional display name reported by the external provider. |
remoteColor |
string |
no |
Optional color reported by the external provider. |
SyncStateView
| Property | Type | Required | Description |
|---|---|---|---|
sourceId |
string |
no | — |
lastSync |
number (int64) |
no | — |
lastError |
string |
no | — |
nextSync |
number (int64) |
no | — |
status |
string [IDLE, RUNNING, OK, ERROR] |
no | — |
ExternalSourceView
| Property | Type | Required | Description |
|---|---|---|---|
syncIntervalSeconds |
number (int64) |
no | — |
creatorId |
string |
no | — |
type |
string |
no | — |
url |
string |
no | — |
ProviderCapabilities
| Property | Type | Required | Description |
|---|---|---|---|
attachmentEditing |
boolean |
no | — |
readOnly |
boolean |
no | — |
ShareEntry
| Property | Type | Required | Description |
|---|---|---|---|
groupId |
string |
no | — |
permission |
string [READ, WRITE, ADMIN] |
no | — |
userId |
string |
no | — |
ApiError
| Property | Type | Required | Description |
|---|---|---|---|
status |
integer (int32) |
yes | — |
code |
string |
yes | — |
message |
string |
yes | — |
details |
array<object> |
no | — |
CalendarCreate
| Property | Type | Required | Description |
|---|---|---|---|
name |
string |
no | Replaces or clears the local calendar name override.
Local calendars require a non-empty name during commit. External calendars may use their remote name when this value is empty. |
externalSource |
ExternalSourceUpdate |
no |
Replaces or clears the external source configuration. |
color |
string |
no |
Optional calendar color in CSS hexadecimal notation. |
shares |
array<ShareEntry> |
no |
Calendar shares that define user and group permissions. |
reminderDefault |
boolean |
no |
Whether new events use the default reminder setting. |
ExternalSourceUpdate
| Property | Type | Required | Description |
|---|---|---|---|
syncIntervalSeconds |
number (int64) |
no | — |
authData |
string |
no | — |
type |
string |
no | — |
url |
string |
no | — |