Start a Voxbi AI Chat session (user)

# Copy for LLM

Mints the short-lived chat token that POST /api/v1/chat/message (and, for a client that wants raw MCP transport instead, POST /mcp/cockpit) requires.

This is the only endpoint in the Voxbi AI Chat surface that accepts an ordinary user app token (a Sanctum token minted with no explicit abilities, which Sanctum stores as ["*"]). Every other call in this flow requires the token returned here instead.

The minted token carries abilities exactly ["mcp:use"] and expires after MCP_SESSION_TTL_MINUTES (default 15 minutes). It is deliberately narrower than the caller's own app token: the assistant holds it for the life of one conversation, and revoking it does not end the user's app session. Minting again immediately revokes any chat token this user already held, so a user has at most one live chat session.

The plaintext token is returned once and cannot be retrieved again. When a long-running conversation gets a 403 from POST /api/v1/chat/message because the token expired mid-conversation, the client's only recovery is to call this endpoint again (the app token is still valid) and resume with the new chat token; the message history the client already holds is unaffected and is simply replayed on the next /chat/message call.

Authorization

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>

Responses

200 401 403 500

A new chat session token.

Response schema

Expand allCollapse all

dataobject

tokenstring

The plaintext chat session token. Send it as `Authorization: Bearer <token>` on `POST /api/v1/chat/message`.

example: 9f8b1c2d-0000-4a1b-9c3d-000000000001|Zt7Qk2xR8vLmA1sD4fG6hJ9kN0pB3cE5uY7iO2wT

expires_atstring · date-time

ISO 8601 expiry. After this the token is rejected with 401/403.

example: 2026-09-04T21:15:00+00:00

Authorization Token Missing. This error is returned when the authorization token is missing.

Response schema

errorstring

Error message

example: Authorization Token is missing

The principal is not a user. PBX-owned API-key tokens are rejected: there is no Voxbi AI Chat surface for a PBX principal.

Response schema

messagestring

example: This action is unauthorized.

The session could not be minted.

Response schema

messagestring

example: Exception occurred while starting a chat session.

post https://cockpit.voxbi.com/api/v1/chat/session

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/chat/session' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Copy

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

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

Copy

import requests

response = requests.post('https://cockpit.voxbi.com/api/v1/chat/session',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'}
)
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",
    ],
]);

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

Sample response

Expand all Collapse all Copy

{ … }

"data": { … }

"token": "9f8b1c2d-0000-4a1b-9c3d-000000000001|Zt7Qk2xR8vLmA1sD4fG6hJ9kN0pB3cE5uY7iO2wT",

"expires_at": "2026-09-04T21:15:00+00:00"

}

}

Sample response Response headers

Expand all Collapse all Copy

{ … }

"error": "Authorization Token is missing"

}

Cache-Control string

example: private, must-revalidate

Connection string

example: keep-alive

Content-Type string

example: application/json

Vary string

example: Origin

X-RateLimit-Limit integer

Max requests allowed in the current rate-limit window.

example: 60

X-RateLimit-Remaining integer

Requests remaining in the current rate-limit window.

example: 57

Sample response

No example for this status.

Sample response

No example for this status.