List IVRs (user, pbx)

Returns a paginated list of the calling PBX's IVR menus.

Auth. Either a user bearer token (abilities ['*']) or an Integrations API key carrying the ivrs scope. That same ivrs scope also covers /ivr-steps: there is deliberately no separate ivr-steps scope. A key without ivrs responds 403.

Tenancy. The PBX is resolved from the token, never from the request. Only the caller's own IVRs are ever returned and no query parameter can widen that.

Shape. Read-only projection: the legacy voip_ivr_id platform mapping is not exposed. Results are sorted by name ascending unless sort says otherwise. The menu's buttons are opt-in through ?include=steps; the steps key is absent from the payload otherwise.

Searching. ?search= runs a case-insensitive partial match over name and comment, and combines with filter[...], sort and pagination. The whole disjunction stays inside the tenant fence, so search can never reach another PBX's menus.

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

search query · string

Free-text search across the resource's searchable fields.

page query · integer

Page number to fetch. Defaults to `1`.

per_page query · integer

Items per page. Values above the maximum, or below 1, fall back to the maximum, which is also the default.

sort query · string

Field to sort by, `-` prefixed for descending. Allowed: `id`, `name`, `comment`, `announcement_id`, `announcement_language`, `default_action`, `enable_smart_ivr`. Defaults to `name` ascending. Any other field responds 422.

filter[key] query · string

Narrow the list by one or more fields. Allowed keys: `id`, `name`, `comment`, `announcement_id`, `announcement_language`, `default_action`, `enable_smart_ivr`. Combine several with `filter[key1]=value1&filter[key2]=value2`. An unsupported key responds 422.

include query · string

Relation to embed. The only allowed value is `steps`, which adds the menu's keypad buttons under `steps`. Anything else responds 422.

enum: steps

accept header · string

example: application/json

Responses

Response schema

dataarray<object>

[]object

linksobject

firststring

The first page of the resource

example: http://localhost/api/v1/resources?page=1

laststring

The last page of the resource

example: http://localhost/api/v1/resources?page=1

prevnull | string

The previous page of the resource

nextnull | string

The next page of the resource

metaobject

current_pageinteger

The current page of the resource

≥ 1

example: 1

fromnull | integer

The first item of the resource

≥ 1

example: 1

last_pageinteger

The last page of the resource

≥ 1

example: 1

linksarray<object>

urlstring | null

The url of the resource (null for the boundary prev/next links)

example: http://localhost/api/v1/resources?page=1

labelstring

The label of the resource

example: first

activeboolean

The status of the resource

example: 1

pathstring

The path of the resource

example: http://localhost/api/v1/resources

per_pageinteger

The number of items per page of the resource

≥ 1

example: 15

tonull | integer

The last item of the resource

≥ 1

example: 1

totalinteger

The total number of items of the resource

≥ 0

example: 1

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

Unprocessable Query. Two different problems share this status on the read endpoints: * a query parameter has the wrong TYPE (`page` / `per_page` not an integer, `filter` not an array, `sort` not a string). The body carries an `errors` map keyed by parameter name. * a `filter[...]` key, a `sort` field or an `include` relation that the endpoint does not allow was requested. The body carries a single `message` naming the allowed values. Nothing is returned and no partial result is produced: correct the query string and retry.

Response schema

messagestring

Present when an unsupported filter, sort or include was requested. The values it enumerates are the allow-list of the endpoint that returned it, so they differ per endpoint; the examples below show the `/ivrs` allow-list.

errorsobject

Present when a query parameter has the wrong type. Keyed by parameter name.

Free-form object

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/ivrs

Base URL

Request sample

curl -X GET 'https://cockpit.voxbi.com/api/v1/ivrs' \
  -H 'Authorization: Bearer YOUR_TOKEN'

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

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

import requests

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

<?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/ivrs', false, $context);
$data = json_decode($response, true);
print_r($data);

{ … }

"data": [ … ],

{ … }

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

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

"name": "Customer Support Menu",

"comment": "After-hours routing for the support line",

"announcement_id": "550e8400-e29b-41d4-a716-446655440002",

"announcement_language": null,

"default_action": "repeat",

"enable_smart_ivr": false,

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

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

"steps": [ … ]

{ … }

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

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

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

"name": "Sales department",

"option": "1",

"language": null,

"target_type": "App\Models\CallFlow",

"target_id": "550e8400-e29b-41d4-a716-446655440003",

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

"updated_at": "2024-03-01T08:29:07.000000Z"

}

]

}

"links": { … },

"first": "https://cockpit.voxbi.com/api/v1/ivrs?page=1",

"last": "https://cockpit.voxbi.com/api/v1/ivrs?page=1",

"prev": null,

"next": null

"meta": { … }

"current_page": 1,

"from": 1,

"last_page": 1,

"path": "https://cockpit.voxbi.com/api/v1/ivrs",

"per_page": 100,

"to": 1,

"total": 1

}

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

{ … }

"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

{ … }

"message": "Invalid ability provided."

}

Content-Type string

example: application/json

{ … }

"errors": { … }

"per_page": [ … ],

"The per page field must be an integer."

"sort": [ … ]

"The sort field must be a string."

]

}

Content-Type string

example: application/json

{ … }

"message": "Server Error"

}

No matching endpoints

List IVRs (user, pbx)

Responses