Save the caller's calendar assistant preferences (user)

# Copy for LLM

Zero-configuration by design: every field is optional (sometimes), and a request that omits a field leaves that preference untouched. There is no partial-object replacement semantics beyond that.

write_calendar_id and read_calendar_ids are each validated against GET /me/calendar/calendars at save time: a write id must appear there with writable: true, and every read id must appear there at all (the Cockpit sync mirror is never a legal choice for either, because it is excluded from that list). A rejected selection is a 422, not a silent no-op.

Rate limited to 15 requests/minute (throttle:calendar-write).

Authorization Headers

HTTP: bearerAuth

User bearer token. Default authentication for customer-facing endpoints. Obtain a token by calling POST /login with your credentials, then send it on every subsequent request as Authorization: Bearer <token>. The token inherits the permissions and PBX scope of the authenticated user.

HTTP Authorization Scheme

bearer

Bearer format

Bearer <token>

accept header · string

example: application/json

Request body · required · application/json

Request schema

Expand allCollapse all

write_calendar_idstring | null

One of the ids returned by `GET /me/calendar/calendars` with `writable: true`, or null to reset to primary.

length: 0–320

read_calendar_idsarray<string>

Ids returned by `GET /me/calendar/calendars`, merged into the caller's own agenda reads and labelled by source.

[]string

length: 0–320

timezonestring | null

An IANA timezone name, or null to fall back to the chain (`GET /me/calendar/status`'s `timezone_source`).

example: Europe/Luxembourg

colleague_visibilitystring | null

How much of the caller's OWN calendar a colleague read may show. A null value resets to `busy_only`, the safe default, not `details`.

enum: details busy_only null

example: busy_only

Responses

200 401 403 422 429

Response schema

Expand allCollapse all

dataobject

assistant_write_calendar_idstring | null

assistant_read_calendar_idsarray<string>

[]string

assistant_timezonestring | null

assistant_colleague_visibilitystring

enum: details busy_only

Unauthenticated. The `Authorization: Bearer <token>` header was missing, malformed, or names a token that has been revoked or deleted.

Response schema

messagestring

The calendar assistant is not enabled for this account. Returned when there is no `user_provider_mappings` row for the caller carrying the assistant capability, or the capability is present but switched off. There is deliberately no fallback to "assume Microsoft" here, unlike other capabilities on the same table.

Response schema

messagestring

Either standard field validation, or a rejected calendar selection (`write_calendar_id` not writable, or a `read_calendar_ids` entry not in the caller's own calendar list).

Response schema

Expand allCollapse all

messagestring

errorsobject

Free-form object

Too Many Requests. The rate limit for this action has been exceeded. Retry after the window indicated by the Retry-After header.

Response schema

messagestring

put https://cockpit.voxbi.com/api/v1/me/calendar/preferences

Base URL The production API server The staging API server The development API server

Request sample cURL JavaScript Python PHP

Copy

curl -X PUT 'https://cockpit.voxbi.com/api/v1/me/calendar/preferences' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"write_calendar_id":null,"read_calendar_ids":[],"timezone":"Europe/Luxembourg","colleague_visibility":"busy_only"}'

Copy

const response = await fetch('https://cockpit.voxbi.com/api/v1/me/calendar/preferences', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
  body: JSON.stringify({
    "write_calendar_id": null,
    "read_calendar_ids": [],
    "timezone": "Europe/Luxembourg",
    "colleague_visibility": "busy_only"
}),
});

const data = await response.json();
console.log(data);

Copy

import requests

response = requests.put('https://cockpit.voxbi.com/api/v1/me/calendar/preferences',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'},
    json={
    "write_calendar_id": null,
    "read_calendar_ids": [],
    "timezone": "Europe/Luxembourg",
    "colleague_visibility": "busy_only"
}
)
response.raise_for_status()
data = response.json()
print(data)

Copy

<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'PUT',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
        'content' => '{
    \"write_calendar_id\": null,
    \"read_calendar_ids\": [],
    \"timezone\": \"Europe/Luxembourg\",
    \"colleague_visibility\": \"busy_only\"
}',
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/me/calendar/preferences', false, $context);
$data = json_decode($response, true);
print_r($data);

Sample request

Expand all Collapse all Copy

{ … }

"write_calendar_id": null,

"read_calendar_ids": [],

"timezone": "Europe/Luxembourg",

"colleague_visibility": "busy_only"

}

Sample response

Expand all Collapse all Copy

{ … }

"data": { … }

"assistant_write_calendar_id": null,

"assistant_read_calendar_ids": [],

"assistant_timezone": "Europe/Luxembourg",

"assistant_colleague_visibility": "busy_only"

}

}

Sample response Response headers

Expand all Collapse all Copy

{ … }

"message": "Unauthenticated."

}

Content-Type string

example: application/json

Sample response

Expand all Collapse all Copy

{ … }

"message": "The calendar assistant is not enabled for this account."

}

Sample response

Expand all Collapse all Copy

{ … }

"message": "The given data was invalid.",

"errors": { … }

"timezone": [ … ]

"The timezone field must be a valid timezone."

]

}

}

Sample response Response headers

Expand all Collapse all Copy

{ … }

"message": "Too Many Attempts."

}

Retry-After integer

Seconds to wait before retrying.

example: 60

Content-Type string

example: application/json