Suggest open meeting slots across the caller and colleagues (user)

# Copy for LLM

Free/busy across the caller's own mailbox and the given colleagues, reduced to open windows of at least duration_minutes. Colleagues who have not enabled the assistant are silently skipped rather than failing the whole request. Only busy/free windows are considered; subjects, locations and attendee lists never enter this computation on either provider.

Requires the ListUsers permission - the same gate as GET /users/{user}/calendar/* - because colleague_ids reaches the identical colleague-mailbox resolution those routes use.

colleague_ids names colleagues by their internal user id, never by email, and each id must exist in the caller's own PBX (Rule::exists scoped by pbx_id); capped at 19 (20 mailboxes total with the caller).

The window may not span more than 62 days, same rule as GET /me/calendar/agenda.

Rate limited to 10 requests/minute (throttle:calendar-availability): this endpoint fans out up to 20 provider calls per request against a shared per-project quota.

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

earliest*string · date-time

latest*string · date-time

Must be after `earliest`, and no more than 62 days after it.

duration_minutes*integer

≥ 5≤ 1440

colleague_idsarray<string>

items: 0–19

[]string · uuid

Responses

200 401 403 422 429

OK. `data` is omitted entirely when no open slot qualifies.

Response schema

Expand allCollapse all

dataarray<object>

startstring · date-time

endstring · date-time

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

Response schema

messagestring

Either the caller lacks `ListUsers` (the FormRequest's own `authorize()` check, evaluated before any other check), or the caller's own assistant is not enabled.

Response schema

messagestring

`earliest`/`latest`/`duration_minutes` missing or invalid, the window spans more than 62 days, or a `colleague_ids` entry does not exist in the caller's PBX.

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

post https://cockpit.voxbi.com/api/v1/me/calendar/availability

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

Request sample cURL JavaScript Python PHP

Copy

curl -X POST 'https://cockpit.voxbi.com/api/v1/me/calendar/availability' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"earliest":"2026-09-08T00:00:00Z","latest":"2026-09-12T00:00:00Z","duration_minutes":30,"colleague_ids":["550e8400-e29b-41d4-a716-446655440000"]}'

Copy

const response = await fetch('https://cockpit.voxbi.com/api/v1/me/calendar/availability', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
  body: JSON.stringify({
    "earliest": "2026-09-08T00:00:00Z",
    "latest": "2026-09-12T00:00:00Z",
    "duration_minutes": 30,
    "colleague_ids": [
        "550e8400-e29b-41d4-a716-446655440000"
    ]
}),
});

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

Copy

import requests

response = requests.post('https://cockpit.voxbi.com/api/v1/me/calendar/availability',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'},
    json={
    "earliest": "2026-09-08T00:00:00Z",
    "latest": "2026-09-12T00:00:00Z",
    "duration_minutes": 30,
    "colleague_ids": [
        "550e8400-e29b-41d4-a716-446655440000"
    ]
}
)
response.raise_for_status()
data = response.json()
print(data)

Copy

<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
        'content' => '{
    \"earliest\": \"2026-09-08T00:00:00Z\",
    \"latest\": \"2026-09-12T00:00:00Z\",
    \"duration_minutes\": 30,
    \"colleague_ids\": [
        \"550e8400-e29b-41d4-a716-446655440000\"
    ]
}',
    ],
]);

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

Sample request

Expand all Collapse all Copy

{ … }

"earliest": "2026-09-08T00:00:00Z",

"latest": "2026-09-12T00:00:00Z",

"duration_minutes": 30,

"colleague_ids": [ … ]

"550e8400-e29b-41d4-a716-446655440000"

]

}

Sample response

Expand all Collapse all Copy

{ … }

"data": [ … ]

{ … }

"start": "2026-09-08T13:00:00+00:00",

"end": "2026-09-08T14:00:00+00:00"

}

]

}

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": "This action is unauthorized."

}

Sample response

Expand all Collapse all Copy

{ … }

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

"errors": { … }

"latest": [ … ]

"The window may not span more than 62 days."

]

}

}

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