Get a Statu

# Copy for LLM

Returns the status identified by the path parameter. Requires the statuses scope on an Integrations API key (a user bearer token also passes). Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX, so another PBX's status id returns 404.

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>

HTTP: IntegrationApiKey

API key created on the Cockpit Integrations page (an "API key" integration). It is a bearer token owned by the customer's PBX and limited to the scopes selected when the key was created (e.g. phone-numbers, push-configuration).

Send it in the Authorization header:

Authorization: Bearer <api_key>

Manage keys (create / reveal / revoke) from Integrations → New integration → API key.

HTTP Authorization Scheme

bearer

id path · string · uuid *

accept header · string

example: application/json

Responses

200 401 403 5XX

Response schema

Expand allCollapse all

id*string · uuid

Unique status identifier.

read-only

example: 550e8400-e29b-41d4-a716-446655440000

name*string

Human-readable name of the status as shown to users.

length: 0–255

example: Working

description*string | null

Optional free-form description of what the status represents.

example: Standard work activity

style*object | null

Visual styling for the status pill (icon and colours). Null when no styling has been configured.

icon_classstring | null

Font Awesome icon identifier rendered with the status (for example briefcase, coffee, headset).

example: briefcase

font_colorstring | null

Hex colour used for the foreground text of the status pill.

example: #FFFFFF

bg_colorstring | null

Hex colour used as the background of the status pill.

example: #1F8F4E

availability*string | null

Roll-up availability category exposed to telephony and presence features. Null when the status has no mapped availability.

enum: available unavailable busy meeting away

example: available

meta_data*object | null

Extended behavioural settings. The `flags` array carries opt-in switches that drive status behaviour, such as `payable`, `pbx_reachable`, `do_not_disturb`, `chat_available`, `temp_break`, `calculate_lunch_time`, `pbx_not_reachable`, and `auto_stop_target`. Additional implementation keys may also be present.

flagsarray<string>

Behavioural flags currently enabled on this status.

[]string

enum: calculate_lunch_time pbx_reachable payable do_not_disturb chat_available temp_break pbx_not_reachable auto_stop_target

allow_multiselect*boolean

Whether more than one sub-status can be selected at once while in this status. Defaults to false.

example:

sub_status_selection_mandatory*boolean

Whether the user must pick a sub-status when entering this status. Defaults to false.

example:

sub_statuses*array<object>

Sub-statuses attached to this status. Only populated when the `subStatuses` relation is eager loaded by the request; otherwise returned as an empty array.

id*string · uuid

Unique identifier of the sub-status.

example: 550e8400-e29b-41d4-a716-446655440010

name*string

Human-readable name of the sub-status.

example: Customer Support

description*string | null

Optional free-form description of the sub-status.

example: Handling inbound support calls

style*object | null

Visual styling for the sub-status, mirroring the parent status `style` object (icon and colours). Null when not configured.

icon_classstring | null

Font Awesome icon identifier for the sub-status.

example: headset

font_colorstring | null

Hex colour used for the foreground text.

example: #FFFFFF

bg_colorstring | null

Hex colour used as the background.

example: #2D6CDF

created_at*string | null · date-time

Timestamp when the status was created.

read-only

example: 2024-03-01T08:29:07Z

updated_at*string | null · date-time

Timestamp when the status was last updated.

read-only

example: 2024-03-01T08:29:07Z

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

Response schema

errorstring

Error message

example: Authorization Token is missing

Forbidden. The bearer token authenticated successfully but does not carry the scope this endpoint requires. Re-create the Integrations API key with the missing scope selected (Integrations > New integration > API key).

Response schema

messagestring

Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue.

Response schema

messagestring

exceptionstring

Only present in non-production environments.

filestring

Only present in non-production environments.

lineinteger

Only present in non-production environments.

get https://cockpit.voxbi.com/api/v1/statuses/{id}

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/statuses/{id}' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Copy

const response = await fetch('https://cockpit.voxbi.com/api/v1/statuses/{id}', {
  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/statuses/{id}',
    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/statuses/{id}', false, $context);
$data = json_decode($response, true);
print_r($data);

Sample response Response headers

Expand all Collapse all Copy

{ … }

"id": "550e8400-e29b-41d4-a716-446655440000",

"pbx_id": "550e8400-e29b-41d4-a716-446655440001",

"parent_id": "550e8400-e29b-41d4-a716-446655440000",

"name": "Working",

"description": "Standard work activity",

"style": { … },

"icon_class": "briefcase",

"font_color": "#FFFFFF",

"bg_color": "#1F8F4E"

},

"availability": "available",

"meta_data": { … },

"flags": [ … ]

"pbx_reachable",

"payable"

]

},

"payable": true,

"allow_multiselect": false,

"sub_status_selection_mandatory": false,

"sub_statuses_enabled": true,

"ring_users_despite_right_to_disconnect": false,

"created_at": "2024-03-01T08:29:07Z",

"updated_at": "2024-03-01T08:29:07Z",

"deleted_at": "2024-03-01T08:29:07Z"

}

Host string

example: cockpit.voxbi.com

Date string

example: Mon, 16 Oct 2023 14:08:48 GMT

Connection string

example: close

Cache-Control string

example: no-cache, private

Content-Type string

example: application/json

X-RateLimit-Limit integer

example: 60

X-RateLimit-Remaining integer

example: 59

Vary string

example: Origin

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 Response headers

Expand all Collapse all Copy

{ … }

"message": "Invalid ability provided."

}

Content-Type string

example: application/json

Sample response

Expand all Collapse all Copy

{ … }

"message": "Server Error"

}