Get a colleague's next meeting (user)

# Copy for LLM

GET only, and this route group registers no other verb, ever - see GET /users/{user}/calendar/agenda for the full protocol note.

Requires the ListUsers permission. A cross-tenant or nonexistent {user} both 404 identically. Sensitivity and colleague_visibility reduction apply exactly as on the agenda read. Unlike the agenda read, this endpoint returns the snake_case CalendarEvent model, matching the caller's own GET /me/calendar/next.

If the colleague has not enabled the assistant, or has no upcoming meeting, this answers 200 with the data key omitted entirely.

Authorization Parameters 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>

user path · string · uuid *

accept header · string

example: application/json

Responses

200 401 403 404

OK. `data` is omitted when not enabled or there is no upcoming meeting.

Response schema

Expand allCollapse all

dataobject

A single calendar event, normalised away from whichever provider (Microsoft or Google) produced it. This is the shape returned by `GET /me/calendar/events/{event}`, `POST /me/calendar/events`, `PATCH /me/calendar/events/{event}`, `GET /me/calendar/next` and `GET /users/{user}/calendar/next`. **Not the shape of `GET /me/calendar/agenda` or `GET /users/{user}/calendar/agenda`.** Those two endpoints currently serialise the underlying event data directly (camelCase field names, e.g. `seriesMasterId` instead of `series_master_id`), while every other endpoint on this page goes through this snake_case model. This is a known, tracked inconsistency in the API today, not a documentation error; see the `agenda` operations for the exact camelCase shape they return.

id*string

Provider-native event id. Opaque; do not parse it.

example: AAMkAGI1AAAtOTU1AAA=

deleted*boolean

True when the provider is reporting this event as removed. A deleted event carries no other field but `id` (and `calendar_id`, if known) - every other field is absent rather than stale.

example:

series_master_idstring | null

Id of the recurring series this event belongs to, or null for a non-recurring event.

subjectstring | null

Event title. Null when the provider did not say.

example: Weekly Sync

startstring | null · date-time

Start time, always UTC regardless of the mailbox's own timezone.

example: 2026-09-08T09:00:00Z

endstring | null · date-time

End time, always UTC regardless of the mailbox's own timezone.

example: 2026-09-08T09:30:00Z

is_all_day*boolean

example:

is_cancelled*boolean

True when the organizer cancelled the event (distinct from `deleted`, a tombstone).

example:

show_asstring | null

How the event presents the owner's availability. Null when the provider did not say.

enum: free tentative busy oof workingElsewhere null

example: busy

sensitivitystring | null

How private the owner marked the event. Null when the provider did not say.

enum: normal personal private confidential null

example: normal

responsestring | null

The mailbox owner's own answer to the invitation.

enum: none organizer tentativelyAccepted accepted declined notResponded null

example: accepted

calendar_idstring | null

Which calendar the event came from. Null means the mailbox's primary calendar.

attendeesarray<object>

Invitees. Null when the provider did not say (never an empty array standing in for "no attendees", which is itself a distinct fact).

emailstring · email

example: jane.smith@example.com

namestring | null

example: Jane Smith

typestring

enum: required optional

example: required

responsestring | null

enum: none organizer tentativelyAccepted accepted declined notResponded null

example: accepted

organizer_emailstring | null · email

example: jane.smith@example.com

locationstring | null

example: Conference Room 2

online_meetingstring | null

Provider-native online-meeting join URL. Null when the event has none.

example: https://meet.example.com/abc-defg-hij

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

Response schema

messagestring

The caller does not hold the `ListUsers` permission required to read a colleague's calendar. Checked before the `{user}` id is resolved, so a caller without the permission never learns whether the id even exists.

Response schema

messagestring

`{user}` does not resolve in the caller's own PBX. Deliberately identical whether the id is simply wrong or belongs to a real user in a different tenant: cross-tenant and nonexistent both 404 the same way, so this route cannot be used as an existence oracle for another tenant's user ids.

Response schema

messagestring

get https://cockpit.voxbi.com/api/v1/users/{user}/calendar/next

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

Request sample cURL JavaScript Python PHP

Copy

curl -X GET 'https://cockpit.voxbi.com/api/v1/users/{user}/calendar/next' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Copy

const response = await fetch('https://cockpit.voxbi.com/api/v1/users/{user}/calendar/next', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
});

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

Copy

import requests

response = requests.get('https://cockpit.voxbi.com/api/v1/users/{user}/calendar/next',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'}
)
response.raise_for_status()
data = response.json()
print(data)

Copy

<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'GET',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/users/{user}/calendar/next', false, $context);
$data = json_decode($response, true);
print_r($data);

Sample response

Expand all Collapse all Copy

{ … }

"data": { … }

"id": "AAMkAGI1AAAtOTU1AAA=",

"deleted": false,

"series_master_id": null,

"subject": null,

"start": "2026-09-08T09:00:00Z",

"end": "2026-09-08T09:30:00Z",

"is_all_day": false,

"is_cancelled": false,

"show_as": "busy",

"sensitivity": null,

"response": null,

"calendar_id": null,

"attendees": null,

"organizer_email": null,

"location": null,

"online_meeting": null

}

}

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": "You are not authorized to view a colleague's calendar."

}

Sample response

No example for this status.