Skip to content
Optiwork API Docs

List calendars

GET
/calendars
curl --request GET \
  --url https://calendar.work.optidata.cloud/api/calendars \
  --header 'Authorization: Bearer <token>'

Every calendar the authenticated user can see: the ones they own, plus the ones other users have shared with them. Calendars the user owns come first; shared ones follow.

The user’s primary calendar is the one with isHomeCalendar: true. It cannot be renamed or deleted, which is why it also reports isDeletable: false.

Authorizations

Section titled “Authorizations”

Responses

Section titled “ Responses ”

200

Section titled “200”

The calendars visible to the caller.

Media typeapplication/json
object
calendars
required
Array<object>

A calendar the caller owns or has been given access to.

object
id
required

Id of the calendar, as digits.

string | null
sharedId

For a calendar shared with the caller, its {ownerZid}:{calendarId} identifier. null for a calendar the caller owns.

string | null
uuid
string | null
name
required
string | null
color

Hex colour used to render the calendar.

string | null
exportUrl

Populated only when a subscription feed has been generated.

string | null
folderPath
string | null
parentFolderId
string | null
parentFolderUuid
string | null
linkedCalendarId

For a shared calendar, its id in the owner’s account.

string | null
linkedCalendarUuid
string | null
ownerZid
string | null
ownerEmail
string | null
ownerName
string | null
userRole
One of:

What a member may do with a calendar. viewer reads it, manager also creates and edits events and may answer invitations on the owner’s behalf, admin additionally manages sharing, and owner is the person the calendar belongs to.

string
Allowed values: viewer manager admin owner
isHomeCalendar
required

true for the user’s primary calendar, which cannot be renamed or deleted.

boolean
isDeletable
required
boolean
isShared
required

true when the calendar belongs to somebody else.

boolean
isBroken
required

true when a shared calendar can no longer be resolved — usually because the owner revoked access or deleted it.

boolean
permissions
required

Who the calendar is shared with, and at which role.

Array<object>

One person’s access to a calendar.

object
role

What a member may do with a calendar. viewer reads it, manager also creates and edits events and may answer invitations on the owner’s behalf, admin additionally manages sharing, and owner is the person the calendar belongs to.

string
Allowed values: viewer manager admin owner
memberType

user is somebody with an Optiwork account in the tenant, group a user group, and guest an address outside it.

string
Allowed values: user guest group
memberZid

Mailbox identifier of the member.

string | null
memberEmail

Address of the member.

string | null
memberName
string | null
memberAvatarUrl
string | null
memberOptiworkIdentifier

Optiwork identifier of the member — the value to send back as optiworkIdentifier.

string | null
Examples
Examplecalendars
{
  "calendars": [
    {
      "id": "10",
      "sharedId": null,
      "uuid": "4efee8cc-dc50-4974-ac04-fa4a8510cf29",
      "name": "Calendar",
      "color": "#9C5DEF",
      "exportUrl": null,
      "folderPath": "/Calendar",
      "parentFolderId": "1",
      "parentFolderUuid": "467ce5ad-84c6-4825-889b-9a28e96bbe4a",
      "linkedCalendarId": null,
      "linkedCalendarUuid": null,
      "ownerZid": null,
      "ownerEmail": null,
      "userRole": "owner",
      "isHomeCalendar": true,
      "isDeletable": false,
      "isShared": false,
      "isBroken": false,
      "permissions": [
        {
          "role": "owner",
          "memberType": "user",
          "memberZid": "20d77f6c-91f6-4e39-9488-bb7fe302d65d",
          "memberEmail": "jane.doe@acme.example",
          "memberName": "Jane Doe",
          "memberAvatarUrl": null,
          "memberOptiworkIdentifier": "9e926fb1-e1ff-4fc9-81a1-5740f10ba57f"
        }
      ],
      "ownerName": null
    },
    {
      "id": "454",
      "sharedId": null,
      "uuid": "2ca985db-cc36-4627-aef2-3ee45fdf0fdd",
      "name": "Team planning",
      "color": "#EBBC00",
      "folderPath": "/Team planning",
      "userRole": "owner",
      "isHomeCalendar": false,
      "isDeletable": true,
      "isShared": false,
      "isBroken": false,
      "permissions": []
    }
  ]
}

401

Section titled “401”

Missing, malformed or expired authentication key.

Media typeapplication/json

Authentication failures use an error key rather than message.

object
error
required
string
Examples
Examplemissing

No bearer token sent

{
  "error": "JWT passport exception: Missing bearer token in request"
}

429

Section titled “429”

Rate limit exceeded. Retry after the window resets.

Media typeapplication/json

Generic error envelope used by policy, binding and framework failures.

object
message
required

Human-readable description of the failure.

string
Examples
Examplethrottled
{
  "message": "Too Many Attempts."
}