Skip to content
calternal docs

Update Calendar preferences

PUT
/api/v1/calendar/preferences
curl --request PUT \
  --url https://example.com/api/v1/calendar/preferences \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "date_format": "system", "default_event_calendar_id": "example", "first_day_of_week": "system", "hour_height": 1, "snap_to_items": true, "snap_to_now": true, "time_format": "system", "time_step_minutes": 5 }'

Requires a signed-in User. It merges supplied display and drag settings with the saved settings. It returns 400 when a value is invalid or 409 when another update prevents the change. Route: /api/v1/calendar/preferences. Inputs: . Do not automatically replay this operation after an uncertain result.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

A change to Calendar preferences. Omitted fields keep their stored values, so a change in one Installation does not reset the User’s other choices.

object
date_format
One of:

The numeric date pattern used by human-readable Calendar and UI labels.

string
Allowed values: system dmy_slash_padded_short mdy_slash_short dmy_slash_short mdy_slash_long dmy_slash_padded_long dmy_dot dmy_dash ymd_slash ymd_dot iso
default_event_calendar_id

Select a default Event calendar. null clears the saved choice; omission keeps it for partial updates.

string | null
first_day_of_week
One of:

The weekday shown at the start of calendar weeks.

string
Allowed values: system sunday monday saturday
hour_height
integer | null format: int32
snap_to_items

Align pointer edits with nearby item edges.

boolean | null
snap_to_now

Align pointer edits with the current-time line.

boolean | null
time_format
One of:

The clock cycle used by human-readable time labels.

string
Allowed values: system 24_hour 12_hour
time_step_minutes

Grid interval: 5, 10, 15 or 30 minutes.

integer | null format: int32
>= 5 <= 30 multiple of 5
Allowed values: 5 10 15 30

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json

Calendar preferences that follow the User to every Installation.

object
date_format
required

Numeric date pattern, or system for the Installation’s locale.

string
Allowed values: system dmy_slash_padded_short mdy_slash_short dmy_slash_short mdy_slash_long dmy_slash_padded_long dmy_dot dmy_dash ymd_slash ymd_dot iso
default_event_calendar_id

Stable ID of the User’s default Event calendar, or None when no Calendar is connected yet.

string | null
first_day_of_week
required

Week start, or system for the Installation’s locale.

string
Allowed values: system sunday monday saturday
hour_height
required

Week and Day zoom: the height of one hour in CSS pixels, 24 to 160.

integer format: int32
snap_to_items
required

Align dragged items with nearby item edges when the pointer is close.

boolean
snap_to_now
required

Align dragged items with the current-time line when the pointer is close.

boolean
time_format
required

Clock cycle, or system for the Installation’s locale.

string
Allowed values: system 24_hour 12_hour
time_step_minutes
required

Grid interval for pointer and keyboard movement: 5, 10, 15 or 30 minutes.

integer format: int32
>= 5 <= 30 multiple of 5
Allowed values: 5 10 15 30
Example
{
  "date_format": "system",
  "first_day_of_week": "system",
  "time_format": "system",
  "time_step_minutes": 5
}

400

Section titled “400”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

403

Section titled “403”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

409

Section titled “409”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}