Pexip_Infinity_Management_API_v37.a
Pexip_Infinity_Management_API_v37.a
Management API
Software Version 37
March 2025
Pexip Infinity Management API
Contents
Introduction 5
About Pexip Infinity 5
About this guide 5
Definitions 5
Intended audience and references 6
Configuration API 9
Configuration resources 9
Resource details 12
Resource methods 12
Getting resource details 12
Creating a single resource object 13
Updating a single resource object 13
Updating multiple resource objects 13
Deleting all resource objects 13
Examples 14
Creating a Virtual Meeting Room, Virtual Auditorium, Virtual Reception, or Test Call Service 14
Getting a Virtual Meeting Room's configuration 15
Changing an existing Virtual Meeting Room 16
Adding a Virtual Meeting Room alias 16
Deleting a Virtual Meeting Room 16
Creating a Virtual Meeting Room with aliases 17
Getting all Virtual Meeting Rooms, Virtual Auditoriums and Virtual Receptions 17
Getting all Virtual Meeting Rooms only 17
Creating multiple Virtual Meeting Rooms 18
Deleting multiple Virtual Meeting Rooms 18
Creating a Virtual Auditorium 18
Creating a Virtual Reception 19
Creating Automatically Dialed Participants 19
Modifying an Automatically Dialed Participant 19
Removing an Automatically Dialed Participant from a Virtual Meeting Room 20
Deleting an Automatically Dialed Participant 20
Creating Call Routing Rules 20
Deleting a Call Routing Rule 21
Status API 26
Status resources 26
Specifying the object ID in the path 27
Resource details 27
Resource methods 27
Pagination and filtering 28
Examples 28
Getting all active conference instances 28
Getting all active Virtual Meeting Room conferences 28
Getting all participants for a conference 29
Getting the media statistics for a participant 31
Getting the status of a Conferencing Node 32
Getting the load for a system location 32
Getting all registered aliases 32
Listing all cloud overflow Conferencing Nodes 32
Listing all locations monitored for dynamic bursting 33
Listing all locations containing dynamic bursting Conferencing Nodes 34
History API 35
History resources 35
Resource details 35
Resource methods 35
Pagination and filtering 36
Examples 36
Getting all conference instances 36
Getting all participants for a conference instance 36
Getting all participants for a time period 39
Getting all participants with packet loss 39
Command API 40
Command resources 40
Resource details 41
Resource methods 41
Response format 41
Examples 42
Dialing a participant into a conference 42
Disconnecting a participant 42
Muting a participant 43
Muting all Guest participants 43
Unmuting a participant 43
Unmuting all Guest participants 43
Locking a conference instance 44
Unlocking a conference instance 44
Unlocking a participant 44
Transferring a participant 44
Changing a participant's role 45
Changing a conference's layout 45
Creating a system backup 45
Restoring a system backup 46
Starting an overflow Conferencing Node 47
Taking a system snapshot 47
Introduction
This guide describes how to use the Pexip Infinity version 37 API. It comprises the following sections:
l Using the management API: an overview of the RESTful web API used to communicate with a Pexip InfinityManagement Node.
l Configuration API: how to configure the Pexip Infinity platform and services (Virtual Meeting Rooms, Virtual Auditoriums, Virtual
Receptions and the Infinity Gateway).
l Status API: how to obtain status information on the Pexip Infinity platform and services.
l History API: how to obtain historical information on the Pexip Infinity platform and services.
l Command API: how to control aspects of Pexip Infinity conference instances.
l Retrieving, paginating, filtering and ordering resource details: how to control which resource details are retrieved.
Definitions
In the context of this API guide:
l A service is a Virtual Meeting Room, Virtual Auditorium, Virtual Reception or Infinity Gateway.
l A conference instance is a unique conference that is created when one or more participants accesses a service, and exists only
until the last participant leaves.
JSON
l http://en.wikipedia.org/wiki/JSON
l http://www.json.org/
l https://tools.ietf.org/html/rfc4627
REST
l http://en.wikipedia.org/wiki/Representational_state_transfer
l http://www.ibm.com/developerworks/webservices/library/ws-restful/
Python
l http://en.wikipedia.org/wiki/Python_(programming_language)
l http://www.python.org/about/gettingstarted/
l http://docs.python-requests.org/en/latest/
l http://pysnmp.sourceforge.net
See the Command API, Configuration API and Status API sections for a list of all resources and how to access the schemas for each.
Authentication
There are three options for API authentication:
l Using OAuth. This option allows the API to authenticate once to authorize access for a set amount of time, after which it must re-
authenticate. This option is useful for environments where a large number of API requests are expected, because it reduces the
number of requests sent to the LDAP server.
l Using an LDAP database. In this case, each API request requires a preceding request to the LDAP server. If you are using an LDAP
database, we recommend you create an account specifically for use by the API.
l If you are not using OAuth or an LDAP database for authentication, access is via the credentials for the web admin user. The
default username for this account is admin.
You can use OAuth and LDAP either on their own or together. Any access that is not via OAuth uses HTTP Basic Authentication over
HTTPS.
Conferencing Nodes), configuration replication intervals are extended, and it may take longer for configuration changes to be applied
to all Conferencing Nodes (the administrator log shows when each node has been updated).
API performance
Accessing the REST API on the Management Node requires that the Management Node lock access to its database to ensure that
configuration remains consistent and coherent. This therefore limits the rate at which requests can be serviced (to 1,000 requests
every 60 seconds).
When configuration is modified, the modified configuration is replicated to the various Conferencing Nodes. This means that
configuration changes cause some CPU usage on both the Management Node and the Conferencing Nodes.
Heavy or frequent API usage will consume resources across the Pexip Infinity deployment.
Security
We recommend that you upload a HTTPS certificate to your Management Node and each Conferencing Node, and that client
applications verify those certificates when connecting to those servers.
Configuration API
Configuration of the Pexip Infinity platform and services can be performed through the REST API, allowing you to create, view, edit and
delete items.
Configuration resources
A summary of the schema for configuration resources is available from the:
l Management Node web interface via https://<manageraddress>/admin/platform/schema/
l REST API via https://<manageraddress>/api/admin/configuration/v1/
The following configuration resources are available via the REST API:
Component Path
System configuration
Platform configuration
Component Path
Licensing /api/admin/configuration/v1/licence/
CA certificate /api/admin/configuration/v1/ca_certificate/
Call control
Service configuration
Component Path
Device /api/admin/configuration/v1/device/
Users
Authentication /api/admin/configuration/v1/authentication/
Permission /api/admin/configuration/v1/permission/
AD FS servers /api/admin/configuration/v1/adfs_auth_server/
AD FS domains /api/admin/configuration/v1/adfs_auth_server_domain/
Users /api/admin/configuration/v1/end_user/
Web app
Utilities
Upgrade /api/admin/configuration/v1/upgrade/
Component Path
† We do not currently recommend creation, deletion or modification of these resources directly; this should only be done by the Secure
Scheduler for Exchange service.
Resource details
More information can be obtained for each resource by downloading the resource schema in a browser. You may want to install a
JSON viewer extension to your browser in order to view the JSON strings in a readable format.
For example, to view the schema for aliases the URI would be:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/schema/?format=json
Resource methods
Each configuration resource supports the following HTTP methods:
Method Action
PATCH Updates an existing resource object, or creates the object if it does not already exist
Note that Pexip Infinity always allocates a new object ID when creating a new resource.
whereas to delete the single Virtual Meeting Room with ID 1 only, the URI is:
"https://<manageraddress>/api/admin/configuration/v1/conference/1/"
Examples
Creating a Virtual Meeting Room, Virtual Auditorium, Virtual Reception, or Test Call Service
To create a new Virtual Meeting Room, Virtual Auditorium, Virtual Reception, or Test Call Service, you must submit a POST to the URI
for this resource. You must specify the service_type as follows:
The following example creates a new Virtual Meeting Room with the name VMR_1. It has no aliases.
import json
import requests
response = requests.post(
"https://<manageraddress>/api/admin/configuration/v1/conference/",
auth=('<user1>', '<password1>'),
verify=True,
json={'name': 'VMR_1', 'service_type': 'conference'}
)
print("Created new Virtual Meeting Room:", response.headers['location'])
Example output
Virtual Meeting Room: {
'aliases': [
{
'alias': '[email protected]',
'conference': '/api/admin/configuration/v1/conference/1/',
'creation_time': '2017-05-11T22:02:05.855877',
'description': '',
'id': 1
}
]
'allow_guests': False,
'automatic_participants': [],
'call_type': 'video',
'creation_time': '2017-05-11T22:02:05.848612',
'crypto_mode: '',
'description': '',
'enable_active_speaker_indication': false,
'enable_chat': 'default',
'enable_overlay_text': false,
'force_presenter_into_main': false,
'guest_identity_provider_group': '',
'guest_pin': '',
'guest_view': None,
'guests_can_present': true,
'host_identity_provider_group': '',
'host_view': 'one_main_seven_pips',
'id': 1,
'ivr_theme': None,
'match_string': '',
'max_callrate_in': None,
'max_callrate_out': None,
'max_pixels_per_second': None,
'mssip_proxy': null,
'mute_all_guests': false,
'name': 'VMR_1',
'non_idp_paticipants': 'disallow_all',
'participant_limit': None,
'pin': '',
'primary_owner_email_address': '',
'replace_string': '',
'resource_uri': '/api/admin/configuration/v1/conference/1/',
'service_type': 'conference',
'sync_tag': '',
'system_location': null,
'tag': ''
}
Deleting a Virtual Meeting Room will also delete all aliases associated with it.
Note that if there is an existing VMR with the same alias, that alias is removed from the previous VMR and assigned to the new VMR.
Getting all Virtual Meeting Rooms, Virtual Auditoriums and Virtual Receptions
Retrieving all the configured Virtual Meeting Rooms, Virtual Auditoriums and Virtual Receptions is achieved by submitting a GET
request to the resource URI they all share:
import json
import requests
response = requests.get(
"https://<manageraddress>/api/admin/configuration/v1/conference/",
auth=('<user1>', '<password1>'),
verify=True
)
print("Virtual Meeting Rooms:", response.json()['objects'])
This example creates a Call Routing Rule that applies to outbound calls made from Pexip VMRs and routes them to registered devices
only:
import json
import requests
response = requests.post(
"https://<manageraddress>/api/admin/configuration/v1/gateway_routing_rule/",
auth=('<user1>', '<password1>'),
verify=True,
json={
'name': 'Outbound calls to registered devices',
'priority': 60,
'match_incoming_calls': False,
'match_outgoing_calls': True,
'match_string': '.*@mycompany\.com',
'replace_string': '',
'called_device_type': 'registration',
}
)
print("Created new Call Routing Rule:", response.headers['location'])
After the provisioning document has been obtained from the management API as above, it may be injected into the Conferencing Node
to be provisioned as follows:
import requests
with open('conferencing_node.xml', 'rb') as handle:
document = handle.read()
response = requests.post(
"https://<conferencingnodeaddress>:8443/configuration/bootstrap",
verify=True,
headers={'Content-Type': 'text/xml'},
data=document,
)
if response.status_code == requests.codes.ok:
print("Successfully provisioned Conferencing Node")
Note that this API is available only on Conferencing Nodes created using the MANUAL-PROVISION-ONLY deployment type.
response = requests.post(
"https://<manageraddress>/api/admin/configuration/v1/ivr_theme/",
auth=("<user1>", "<password1>"),
json={"name": "New theme"},
verify=True,
)
theme_uri = response.headers["location"]
theme_path = urlsplit(theme_uri).path
response = requests.patch(
theme_uri,
auth=("<user1>", "<password1>"),
files={"package": open("test_theme.zip", "rb")},
verify=True,
)
response = requests.patch(
"https://<manageraddress>/api/admin/configuration/v1/conference/1/",
auth=("<user1>", "<password1>"),
json={"ivr_theme": theme_path},
verify=True,
)
Returning a license
To return a license, send a DELETE request using the format:
import requests
response = requests.delete(
"https://<manageraddress>/api/admin/configuration/v1/licence/<fulfillment_id>",
auth=('<user1>', '<password1>'),
verify=True
)
where:
l the fulfillment ID is a 10 digit number
l you can force offline mode by adding ?offline_mode=True to the end of the URI, in which case it will return with a 202 response
and a Location header telling you where to POST the response document.
Adding a license
To add a license entitlement key, send a POST request using the format:
import json
import requests
response = requests.post(
"https://<manageraddress>/api/admin/configuration/v1/licence/",
auth=('<user1>', '<password1>'),
verify=True,
json={
'entitlement_id' : '<entitlement key>'
}
)
print("Added license entitlement key:", response.headers['location'])
where:
l the entitlement key is in the form XXXX-XXXX-XXXX-XXXX (where X is a hex digit [0-9A-F]) or is in an encoded format such as
SrF1FPcyRjitSHOhtU_XGQ==
l you can force offline mode by adding 'offline_mode' : True to the JSON data, in which case it will return with a 202 response and a
Location header telling you where to GET the request file from, and also where to POST the response document.
where the URL to GET the file from is the one returned in the Location header of the response to the initial activation request.
To upload a license response file for a stored license request:
import requests
with open('response.xml', 'r') as response_file:
response = requests.post(
'https://<manageraddress>/api/admin/configuration/v1/licence_request/<request_id>',
auth=('<user1>', '<password1>'),
verify=True,
files={'response_xml': ('response.xml', response_file.read())})
print(response.status_code)
where:
l 'response_xml' is the path to the file containing the response data
l in this example the response file is called response.xml and is in the current directory; depending on the type of activation key this
could also be a .json file
l the URL to POST to is the one returned in the Location header of the response to the initial activation request.
Generating a CSR
Send a GET request to the gateway token endpoint to receive a JSON response with a key csr that will contain the generated CSR.
If a private key has not already been uploaded, then this will generate a new one internally. Note that there is no way to extract this
generated private key. If knowing the private key is important, then you will need to generate one locally, upload that, and then
generate a new CSR.
Status API
The current status of the Pexip Infinity platform and any conference instances currently in progress can be viewed using the API.
Note that all date and time fields are in UTC format.
If you are using the status API heavily, consider using Event sinks instead, to reduce the load on the Management Node.
Status resources
A summary of the schema for status resources is available from the:
l Management Node web interface via https://<manageraddress>/admin/platform/schema/
l REST API via https://<manageraddress>/api/admin/status/v1/
The following status resources are available via the REST API:
Component Path
Participants /api/admin/status/v1/participant/
Backplanes /api/admin/status/v1/backplane/
Alarms /api/admin/status/v1/alarm/
Licenses /api/admin/status/v1/licensing/
Component Path
Resource details
More information can be obtained for each resource by downloading the resource schema in a browser. You may want to install a
JSON viewer extension to your browser in order to view the JSON strings in a readable format.
For example, to view the schema for conference instances the URI would be:
https://<manageraddress>/api/admin/status/v1/conference/schema/?format=json
Resource methods
Each status resource supports the following HTTP methods:
Method Action
Examples
Example output
Active conferences: [
{
'start_time': '2015-04-02T09:46:06.106482',
'resource_uri': '/api/admin/status/v1/conference/00000000-0000-0000-0000-000000000001/',
'id': '00000000-0000-0000-0000-000000000001',
'name': 'VMR_1',
'service_type': 'conference',
'is_locked': False,
'is_started': True,
'guests_muted': False,
'tag': ''
}
]
Example output
Active participants for VMR_1: [
{
'bandwidth': 576,
'call_direction': 'in',
'call_quality': '1_good',
'call_tag': 'def456',
'call_uuid': '1c26be9c-6511-4e5c-9588-8351f8c3decd',
'conference': 'VMR_1',
'connect_time': '2015-04-02T09:46:11.116767',
'conversation_id': '1c26be9c-6511-4e5c-9588-8351f8c3decd',
'destination_alias': '[email protected]',
'display_name': 'Alice',
'encryption': 'On',
'has_media': false,
'id': '00000000-0000-0000-0000-000000000002',
'idp_uuid': '',
'is_client_muted': false,
'is_direct': false,
'is_disconnect_supported': true,
'is_idp_authenticated': false,
'is_mute_supported': true,
'is_muted': False,
'is_on_hold': False,
'is_presentation_supported': true,
'is_presenting': false,
'is_recording' : false,
'is_streaming': false,
'is_transcribing' : false,
'is_transfer_supported': true,
'license_count': 0,
'license_type': 'nolicense',
'media_node': '10.0.0.1',
'parent_id': '',
'participant_alias': 'Infinity_Connect_10.0.0.3',
'protocol': 'WebRTC',
'proxy_node': '10.10.0.46',
'remote_address': '10.0.0.3',
'remote_port': 54686,
'resource_uri': '/api/admin/status/v1/participant/00000000-0000-0000-0000-000000000002/',
'role': 'chair',
'rx_bandwidth': 0,
'service_tag': '',
'service_type': 'conference',
'signalling_node': '10.0.0.1',
'source_alias': 'Infinity_Connect_10.0.0.3',
'system_location': 'London',
'tx_bandwidth': 0,
'vendor': 'Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.101
Safari/537.36'
},
{
'bandwidth': 768,
'call_direction': 'in',
'call_quality': '1_good',
'call_tag': 'wxyz789',
'call_uuid': 'b0a5b554-d1de-11e3-a321-000c29e37602',
'conference': 'VMR_1',
'connect_time': '2015-04-02T09:46:53.712941',
'conversation_id': 'b0a5b554-d1de-11e3-a321-000c29e37602',
'destination_alias': '[email protected]',
'display_name': 'Bob',
'encryption': 'On',
'has_media': false,
'id': '00000000-0000-0000-0000-000000000003',
'idp_uuid': '',
'is_client_muted': false,
'is_direct': false,
'is_disconnect_supported': true,
'is_idp_authenticated': false,
'is_mute_supported': true,
'is_muted': False,
'is_on_hold': False,
'is_presentation_supported': true,
'is_presenting': false,
'is_recording' : false,
'is_streaming': false,
'is_transcribing' : false,
'is_transfer_supported': true,
'license_count': 1,
'license_type': 'port',
'media_node': '10.0.0.1',
'parent_id': '',
'participant_alias': '[email protected]',
'protocol': 'H323',
'proxy_node': '',
'remote_address': '10.0.0.2',
'remote_port': 11007,
'resource_uri': '/api/admin/status/v1/participant/00000000-0000-0000-0000-000000000003/',
'role': 'chair',
'rx_bandwidth': 7528,
'service_tag': '',
'service_type': 'conference',
'signalling_node': '10.0.0.1',
'source_alias': '[email protected]',
'system_location': 'London',
'tx_bandwidth': 4128,
'vendor': 'TANDBERG (Tandberg 257)'
}
]
Note that:
l Perceived call quality:
o call_quality is the most frequently occurring call quality calculation in the last 3 windows, and is determined as described
below.
o historic_call_quality shows the sequence of call quality calculations over time. For completed calls, the system looks at
packet loss in both directions (Tx and Rx) over multiple 20 second time windows throughout the call and calculates the call
quality per window. Packet loss is used to calculate call quality for a time window: < 1% packet loss is perceived as Good
quality; < 3% is OK; < 10% is Bad; otherwise it is Terrible. These readings are reported as 0 = Unknown, 1 = Good, 2 = OK, 3 =
Bad, 4 = Terrible.
o bucketed_call_qualityis a summary of the call quality calculations. For example, reading [0, 7, 3, 1, 2] from left to right
means there were 0 x Unknown, 7 x Good, 3 x OK, 1 x Bad and 2 x Terrible quality calculations.
Note that historic_call_quality and bucketed_call_quality are not reported in the response to management API requests for all
participants for a conference instance (current and historic), but this data is reported when requesting a specific participant.
l conversation_id is the same as call_uuid except for Skype for Business / Lync calls.
l parent_id is always ''.
l is_transcribing indicates a gateway call to Microsoft Teams or Google Meet where remote transcription has been enabled on that
service.
Example output
Media streams for participant: [
{
'end_time': '',
'id': '1',
'node': '10.0.0.1'
'rx_bitrate': 513,
'rx_codec': 'VP8',
'rx_fps': 31.0,
'rx_jitter': 0.29,
'rx_packet_loss': 0,
'rx_packets_lost': 0,
'rx_packets_received': 28761,
'rx_resolution': '640x480',
'rx_windowed_packet_loss': 0.0,
'start_time': '2015-07-22T13:13:52.921269',
'tx_bitrate': 503,
'tx_codec': 'VP8',
'tx_fps': 30.0,
'tx_jitter': 7.68,
'tx_packet_loss': 0,
'tx_packets_lost': 0,
'tx_packets_sent': 26041,
'tx_resolution': '768x448',
'tx_windowed_packet_loss': 0.0,
'type': 'video'
},
{
'end_time': '',
'id': '0',
'node': '10.0.0.1'
'rx_bitrate': 12,
'rx_codec': 'opus',
'rx_fps': 0.0,
'rx_jitter': 0.56,
'rx_packet_loss': 0,
'rx_packets_lost': 0,
'rx_packets_received': 21148,
'rx_resolution': '',
'rx_windowed_packet_loss': 0.0,
'start_time': '2015-07-22T13:13:52.873617',
'tx_bitrate': 2,
'tx_codec': 'opus',
'tx_fps': 0.0,
'tx_jitter': 0.21,
'tx_packet_loss': 0,
'tx_packets_lost': 0,
'tx_packets_sent': 42386,
'tx_resolution': '',
'tx_windowed_packet_loss': 0.0,
'type': 'audio'
}
]
Example output
Cloud nodes: {
"meta": {
"limit": 20,
"next": null,
"offset": 0,
"previous": null,
"total_count": 2
},
"objects": [
{
"aws_instance_id": "i-edb1ae65",
"aws_instance_ip": "172.30.3.6",
"aws_instance_launch_time": "2016-06-27T23:44:41",
"aws_instance_name": "aws_overflow1",
"aws_instance_state": "stopped",
"cloud_instance_id": "i-edb1ae65",
"cloud_instance_ip": "172.30.3.6",
"cloud_instance_launch_time": "2016-06-27T23:44:41",
"cloud_instance_name": "aws_overflow1",
"cloud_instance_state": "stopped",
"max_hd_calls": 0,
"media_load": 100,
"resource_uri": "/api/admin/status/v1/cloud_node/i-edb1ae65/",
"workervm_configuration_id": 6,
"workervm_configuration_location_name": "AWS",
"workervm_configuration_name": "aws_overflow1"
},
{
"aws_instance_id": "i-cfb0af47",
"aws_instance_ip": "172.30.11.83",
"aws_instance_launch_time": "2016-06-27T23:46:43",
"aws_instance_name": "aws_overflow2",
"aws_instance_state": "stopped",
"cloud_instance_id": "i-cfb0af47",
"cloud_instance_ip": "172.30.11.83",
"cloud_instance_launch_time": "2016-06-27T23:46:43",
"cloud_instance_name": "aws_overflow2",
"cloud_instance_state": "stopped",
"max_hd_calls": 0,
"media_load": 100,
"resource_uri": "/api/admin/status/v1/cloud_node/i-cfb0af47/",
"workervm_configuration_id": 7,
"workervm_configuration_location_name": "AWS",
"workervm_configuration_name": "aws_overflow2"
}
]
}
Note that:
l When a Conferencing Node is not available for use (in this example the instances are "stopped"), Pexip Infinity reports a media
load of 100% to indicate that there is no current capacity available.
l The aws_instance prefixed fields are deprecated. Please use the cloud_instance prefixed fields instead.
Example output
Monitored principal locations: {
"meta": {
"limit": 20,
"next": null,
"offset": 0,
"previous": null,
"total_count": 2
},
"objects": [
{
"free_hd_calls": 31,
"id": 4,
"max_hd_calls": 33,
"media_load": 5,
"name": "London",
"resource_uri": "/api/admin/status/v1/cloud_monitored_location/4/"
},
{
"free_hd_calls": 0,
"id": 2,
"max_hd_calls": 42,
"media_load": 100,
"name": "Oslo",
"resource_uri": "/api/admin/status/v1/cloud_monitored_location/2/"
}
]
}
Example output
Overflow locations: {
"meta": {
"limit": 20,
"next": null,
"offset": 0,
"previous": null,
"total_count": 2
},
"objects": [
{
"free_hd_calls": 31,
"id": 4,
"max_hd_calls": 33,
"media_load": 5,
"name": "London",
"resource_uri": "/api/admin/status/v1/cloud_overflow_location/4/"
"systemlocation_id": 3"
},
{
"free_hd_calls": 0,
"id": 2,
"max_hd_calls": 42,
"media_load": 100,
"name": "Oslo",
"resource_uri": "/api/admin/status/v1/cloud_overflow_location/2/"
"systemlocation_id": 1"
}
]
}
History API
The API can be used to view historical information about Pexip Infinity conference instances that are no longer in progress. For
example, this can be used to obtain Call Detail Records (CDRs) of the Pexip Infinity platform.
Note that all date and time fields are in UTC format.
Up to 10,000 conference instances are retained, along with all the participant instances associated with each of those conferences.
Above 10,000 conference instances, each time a new entry is made the oldest entry is deleted (along with all the participant instances
associated with it).
History resources
A summary of the schema for history resources is available from the:
l Management Node web interface via https://<manageraddress>/admin/platform/schema/
l REST API via https://<manageraddress>/api/admin/history/v1/
The following history resources are available via the REST API:
Component Path
Backplane /api/admin/history/v1/backplane/
Participant /api/admin/history/v1/participant/
Registrations /api/admin/history/v1/registration_alias/
Resource details
More information can be obtained for each resource by downloading the resource schema in a browser. You may want to install a
JSON viewer extension to your browser in order to view the JSON strings in a readable format.
For example, to view the schema for backplane instances the URI would be:
https://<manageraddress>/api/admin/history/v1/backplane/schema/?format=json
Resource methods
Each history resource supports the following HTTP methods:
Method Action
Examples
Note that up to 10,000 conference instances may be stored in the history and by default the response is paginated.
Example output
Conference history: [
{
'duration': 579,
'end_time': '2015-04-10T09:49:26.556929',
'id': '8583f400-7886-48c9-874b-5fefc2ac097e',
'instant_message_count': 0,
'name': 'meet.alice',
'participant_count': 3,
'participants': [
'/api/admin/history/v1/participant/e9883f1d-88ca-495d-8366-b6eb772dfe57/',
'/api/admin/history/v1/participant/5881adda-00ef-4315-8886-5d873d2ef269/',
'/api/admin/history/v1/participant/29744376-0436-4fe1-ab80-06d93c71eb1c/'
],
'resource_uri': '/api/admin/history/v1/conference/8583f400-7886-48c9-874b-5fefc2ac097e/',
'service_type': 'conference',
'start_time': '2015-04-10T09:39:47',
'tag': ''
},
]
Example output
Participants for conference: [
{
'bandwidth': 768,
'call_direction': 'in',
'call_quality': '1_good',
'call_tag': 'wxyz789',
'call_uuid': 'b0a5b554-d1de-11e3-a321-000c29e37602',
'conference': '/api/admin/history/v1/conference/00000000-0000-0000-0000-000000000001/',
'conference_name': 'VMR_1',
'conversation_id': 'b0a5b554-d1de-11e3-a321-000c29e37602',
'disconnect_reason': 'Call disconnected',
'display_name': 'Bob',
'duration': 519,
'encryption': 'On',
'end_time': '2015-04-02T09:55:33.141261',
'has_media': True,
'id': '00000000-0000-0000-0000-000000000003',
'idp_uuid': '',
'is_idp_authenticated': false,
'is_streaming': false,
'license_count': 1,
'license_type': 'port',
'local_alias': '[email protected]',
'media_node': '10.0.0.1',
'media_streams': [
{
'end_time': '2015-07-22T12:43:33.645043',
'id': 36,
'node': '10.0.0.1',
'participant': '/api/admin/history/v1/participant/5881adda-00ef-4315-8886-5d873d2ef269/',
'rx_bitrate': 29,
'rx_codec': 'opus',
'rx_packet_loss': 0.0,
'rx_packets_lost': 0,
'rx_packets_received': 28091,
'rx_resolution': '',
'start_time': '2015-07-22T12:33:31.909536',
'stream_id': '0',
'stream_type': 'audio',
'tx_bitrate': 2,
'tx_codec': 'opus',
'tx_packet_loss': 0.0,
'tx_packets_lost': 0,
'tx_packets_sent': 56347,
'tx_resolution': ''
},
{
'end_time': '2015-07-22T12:43:33.683385',
'id': 37,
'node': '10.0.0.1',
'participant': '/api/admin/history/v1/participant/5881adda-00ef-4315-8886-5d873d2ef269/',
'rx_bitrate': 511,
'rx_codec': 'VP8',
'rx_packet_loss': 0.01,
'rx_packets_lost': 2,
'rx_packets_received': 37027,
'rx_resolution': '1280x720',
'start_time': '2015-07-22T12:33:32.151438',
'stream_id': '1',
'stream_type': 'video',
'tx_bitrate': 511,
'tx_codec': 'VP8',
'tx_packet_loss': 0.0,
'tx_packets_lost': 0,
'tx_packets_sent': 37335,
'tx_resolution': '768x448'
}
],
'parent_id': '29744376-0436-4fe1-ab80-06d93c71eb1c',
'protocol': 'WebRTC',
'proxy_node': 'None',
'remote_address': '10.0.0.2',
'remote_alias': 'Infinity_Connect_Media_10.0.0.2',
'remote_port': 11007,
'resource_uri': '/api/admin/history/v1/participant/00000000-0000-0000-0000-000000000003/',
'role': 'chair',
'service_tag': '',
'service_type': 'conference',
'signalling_node': '10.0.0.1',
'start_time': '2015-04-02T09:46:53.712941',
'system_location': 'London',
'vendor': 'Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.101
Safari/537.36'
},
{
'bandwidth': 0,
'call_direction': 'in',
'call_quality': '0_unknown',
'call_tag': 'def456',
'call_uuid': '1c26be9c-6511-4e5c-9588-8351f8c3decd',
'conference': '/api/admin/history/v1/conference/00000000-0000-0000-0000-000000000001/',
'conference_name': 'VMR_1',
'conversation_id': '1c26be9c-6511-4e5c-9588-8351f8c3decd',
'disconnect_reason': 'Call disconnected',
'display_name': 'Alice',
'duration': 578,
'encryption': 'On',
'end_time': '2015-04-02T09:55:49.348317',
'has_media': False,
'id': '00000000-0000-0000-0000-000000000002',
'is_streaming': false,
'license_count': 0,
'license_type': 'nolicense',
'local_alias': '[email protected]',
'media_node': '10.0.0.1',
'media_streams': [],
'parent_id': '',
'protocol': 'WebRTC',
'proxy_node': 'None',
'remote_address': '10.0.0.2',
'remote_alias': 'Infinity_Connect_10.0.0.2',
'remote_port': 54686,
'resource_uri': '/api/admin/history/v1/participant/00000000-0000-0000-0000-000000000002/',
'role': 'chair',
'service_tag': '',
'service_type': 'conference',
'signalling_node': '10.0.0.1',
'start_time': '2015-04-02T09:46:11.116767',
'system_location': 'London',
'vendor': 'Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.101
Safari/537.36'
}
]
Note that:
l Perceived call quality:
o call_quality is the most frequently occurring call quality calculation, and is determined as described below.
o historic_call_quality shows the sequence of call quality calculations over time. For completed calls, the system looks at
packet loss in both directions (Tx and Rx) over multiple 20 second time windows throughout the call and calculates the call
quality per window. Packet loss is used to calculate call quality for a time window: < 1% packet loss is perceived as Good
quality; < 3% is OK; < 10% is Bad; otherwise it is Terrible. These readings are reported as 0 = Unknown, 1 = Good, 2 = OK, 3 =
Bad, 4 = Terrible.
o bucketed_call_qualityis a summary of the call quality calculations. For example, reading [0, 7, 3, 1, 2] from left to right
means there were 0 x Unknown, 7 x Good, 3 x OK, 1 x Bad and 2 x Terrible quality calculations.
Note that historic_call_quality and bucketed_call_quality are not reported in the response to management API requests for all
participants for a conference instance (current and historic), but this data is reported when requesting a specific participant.
l conversation_id is the same as call_uuid except for Skype for Business / Lync calls.
l parent_id is always ''.
l is_transcribing indicates a gateway call to Microsoft Teams or Google Meet where remote transcription has been enabled on that
service.
The following example uses a filter to find all the participants with a media stream that had receive packet loss greater than 0.5%:
import json
import requests
response = requests.get(
"https://<manageraddress>/api/admin/history/v1/participant/?media_streams__rx_packet_loss__gte=0.5",
auth=('<user1>', '<password1>'),
verify=True
)
print("Participants with high receive packet loss :", response.json()['objects'])
Command API
The command API allows conference control and platform-level operations to be invoked.
Command resources
A summary of the schema for command resources is available from the:
l Management Node web interface via https://<manageraddress>/admin/platform/schema/
l REST API via:
o https://<manageraddress>/api/admin/command/v1/participant/
o https://<manageraddress>/api/admin/command/v1/conference/
o https://<manageraddress>/api/admin/command/v1/platform/
The following command resources are available via the REST API:
Component Path
Dial /api/admin/command/v1/participant/dial/
Resource details
More information can be obtained for each resource by downloading the resource schema in a browser. You may want to install a
JSON viewer extension to your browser in order to view the JSON strings in a readable format.
For example, to view the schema for the dial command the URI would be:
https://<manageraddress>/api/admin/command/v1/participant/dial/schema/?format=json
Each schema contains information on the available fields including:
l whether the field is optional (nullable: true) or required (nullable: false)
l the default value
l the type of data the field must contain
l the choices for the field, e.g. valid_choices: ["audio", "video", "video-only"]
l help text with additional information on usage.
Resource methods
Each command resource supports the following HTTP methods:
Method Action
Response format
The response for a command will be a JSON object with the following attributes:
Attribute Value
Individual commands may have response attributes specific to the command. See the command examples for more information.
Examples
The following example places a call to the alias alice and uses Call Routing Rules. The node/location used to place the call is determined
by whichever Call Routing Rule matches this dial request. The rule can optionally use the Calls being handled in location condition to
test against the nominated source location of London. Alice will see the call as coming from alias [email protected], and on answer
will join the Virtual Meeting Room associated with that alias (in this case VMR_1, based on our configuration API examples), as a Host.
import requests
import json
response = requests.post(
"https://<manageraddress>/api/admin/command/v1/participant/dial/",
auth=('<user1>', '<password1>'),
data={
'conference_alias': '[email protected]',
'destination': 'alice',
'routing': 'routing_rule',
'remote_display_name': 'Alice Parkes',
'role': 'chair',
'system_location': 'London',
},
verify=True)
print("New participant created:", json.loads(response.content)['data']['participant_id'])
Note that if the dial command is successful the response will contain a participant_id attribute which can be used in queries
for status and other conference control commands such as Disconnecting a participant and Muting a participant.
Disconnecting a participant
By submitting a POST request to the disconnect resource URI, an existing participant can be disconnected from a conference
instance.
import requests
response = requests.post(
"https://<manageraddress>/api/admin/command/v1/participant/disconnect/",
auth=('<user1>', '<password1>'),
data={
'participant_id': '00000000-0000-0000-0000-000000000001',
},
verify=True)
Muting a participant
By submitting a POST request to the mute resource URI, the audio being sent from an existing conference participant can be muted,
meaning all other participants will not hear them.
import requests
response = requests.post(
"https://<manageraddress>/api/admin/command/v1/participant/mute/",
auth=('<user1>', '<password1>'),
data={
'participant_id': '00000000-0000-0000-0000-000000000001',
},
verify=True)
Unmuting a participant
By submitting a POST request to the unmute resource URI, a previously muted conference participant will have their audio restored,
meaning other participants will again be able to hear them.
import requests
response = requests.post(
"https://<manageraddress>/api/admin/command/v1/participant/unmute/",
auth=('<user1>', '<password1>'),
data={
'participant_id': '00000000-0000-0000-0000-000000000001',
},
verify=True)
Unlocking a participant
By submitting a POST request to the participant unlock resource URI, a participant held at the Waiting for conference host screen
because the conference has been locked will be allowed to join the conference.
import requests
response = requests.post(
"https://<manageraddress>/api/admin/command/v1/participant/unlock/",
auth=('<user1>', '<password1>'),
data={
'participant_id': '00000000-0000-0000-0000-000000000001',
},
verify=True)
Transferring a participant
By submitting a POST request to the participant transfer resource URI, a participant can be moved from one conference to another.
The target conference is identified by an alias in the conference_alias field, and they will have the specified role.
If the target conference is PIN-protected, the participant will bypass the PIN entry.
import requests
response = requests.post(
"https://<manageraddress>/api/admin/command/v1/participant/transfer/",
auth=('<user1>', '<password1>'),
data={
'participant_id': '00000000-0000-0000-0000-000000000001',
'conference_alias': '[email protected]',
'role': 'guest'
},
verify=True)
The backup file is created on the Management Node under the https://<manageraddress>/api/admin/configuration/v1/system_
backup/ location.
Creating a background backup creation request
You can create a background backup creation request by passing the 'request': true data parameter in the backup_create command.
Your backup API request will immediately respond with a status URI e.g. /api/admin/status/v1/backup_request/1/ which you can poll
to find out when the backup is complete ("state": "complete").
When complete, the status response will also return a download_uri which you can use to download the requested backup file.
An example complete response looks like this:
{
"created_at": "2024-12-13T10:30:55.333208",
"download_uri": "/api/admin/status/v1/backup_request/1/download/",
"message": "",
"resource_uri": "/api/admin/status/v1/backup_request/1/",
"state": "complete",
"updated_at": "2024-12-13T10:31:13.448943"
}
l initialising: the request has been logged but has not yet started.
l running: it is in progress but it is waiting for success or failure.
l complete: finished successfully
l error: an error has occurred and there should be an error message in message
1. List the available backups on the Management Node to identify the filename of the backup you want to restore.
2. Download the backup file to a temporary location.
3. Restore the contents of the backup file to your Pexip Infinity system.
The response will include data similar to this for each backup file:
{
"build": "59437.0.0",
"date": "2021-01-08T15:36:16",
"filename": "pexip_backup_10-44-7-0-mgr_25_59437.0.0_21_01_08_09_05_43.tar.pexbak",
"resource_uri": "/api/admin/configuration/v1/system_backup/pexip_backup_10-44-7-0-mgr_25_59437.0.0_21_01_08_
09_05_43.tar.pexbak/",
"size": 214702132,
"version": "25"
}
The "filename" value is what you will use in place of <filename> in the following GET command to download the file.
Note that if a backup file is no longer needed, you can perform a DELETE on the
https://<manageraddress>/api/admin/configuration/v1/system_backup/<filename>/ URL to delete individual files.
This downloads the backup file to /tmp/temp.bak — you can change this to your preferred location and filename if required.
Using the example response from the list of available backups, the GET would be for:
"https://10.44.7.0/api/admin/configuration/v1/system_backup/pexip_backup_10-44-7-0-mgr_25_59437.0.0_21_01_08_09_05_
43.tar.pexbak/"
You can use the cloud_node status resource to obtain the instance IDs for your overflow nodes.
If the command is successful the response content takes the format: '{"status": "success"}'
If the Conferencing Node is already running, the response is: '{"status": "failed", "error": "Unable to start a cloud node which isn't
in 'STOPPED' state"}'
If the instance_id does not match a cloud overflow node, the response is a 400 Bad Request with the following content: '{"start_
cloudnode": {"instance_id": ["Failed to find the cloud node."]}}'
save_path = "/tmp/"
response = requests.post(
"https://<management-address>/api/admin/command/v1/platform/snapshot/",
auth=(<username>, <password>),
data={"limit": 12}, # hours
stream=True,
verify=True,
)
response.raise_for_status()
content_disposition = response.headers["content-disposition"]
m = re.search("filename=([^ ]+)", content_disposition)
if not m:
raise Exception(f"Failed to find snapshot filename in {content_disposition!r}")
filename = os.path.join(save_path, m.group(1).strip('"'))
print("Saving snapshot to ", filename)
with open(filename, "wb") as fp:
for chunk in response.iter_content(8192):
fp.write(chunk)
The response to a GET for a single resource is a JSON object with attributes for each field of the resource.
The ID of existing objects can be identified from the URI shown in the Administrator interface when viewing the item, for example
when viewing a Virtual Meeting Room the URI is in the format https://<manageraddress>/admin/conferencing/conference/117/change/
where in this case the ID of this VMR is 117.
When using the management API to retrieve information about existing resources, the id field identifies the object ID. In this example
of a VMR resource, the ID is 3:
Attribute Value
For example, to GET all conference aliases the URI would be:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/
Global settings
The global settings (/api/admin/configuration/v1/global/) are a special case.
To make the API as consistent as possible, the global settings are treated in the same way as other resources i.e. there is a list of global
settings. However, you are only allowed one global settings resource. Thus, if you get the list of all global settings you will only ever get
a list with one entry in it. Also, you are not allowed to delete all global settings.
Therefore you should almost always deal directly with the detail of the existing resource (via api/admin/configuration/v1/global/1/)
rather than using it a list.
Pagination
By default, the response is paginated and it contains the first page of 20 results. To retrieve subsequent pages of results the offset
parameter must be specified in the URI.
To carry on from our previous example, to retrieve the second page of results the URI would be:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/?offset=20
The limit parameter can be used to change the number of results in the response.
For example, to return the first 100 objects the URI would be:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/?limit=100
Note that if there are a large number of aliases configured this may put a significant load on both the Management Node and the client
making the request.
Filtering
A request for multiple objects can be filtered so that only those objects that match specific criteria are returned. The table below lists
the available match specifiers.
Note that:
l Filtering is case insensitive for the contains, startswith and endswith keywords (but not exact and regex).
l The lt , lte, gt and gte filters use ordinal comparison for strings — thus Ark < Rock < ark < rock.
Specifier Description
exact Matches objects whose field exactly matches the value (case sensitive).
regex Matches objects whose field matches the regular expression value (case sensitive).
lte Matches objects whose field is less than or equal to the value.
gte Matches objects whose field is greater than or equal to the value.
The criteria that can be used for filtering are included at the end of the schema for each resource. If no filtering section is
present, then filtering is not available.
For example, to see which criteria you can use to filter a search for service aliases, look at the associated schema:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/schema/?format=json
This indicates that you can filter by any of the criteria listed above. The 1 and 2 following each criteria indicate that all of the match
specifiers listed in the table above are valid when filtering using that criteria. Alternatively, if not all specifiers are valid, those that are
valid are listed instead.
For example, to search for information about the alias meet.alice the URI would be:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/?alias=meet.alice
For example, to search for all aliases that start with meet. the URI would be:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/?alias__startswith=meet.
To query in an array, for example aliases, you must query on items inside the array i.e. aliases__alias. For example, to display all VMRs
containing an alias in a URI format:
https://<manageraddress>/api/admin/configuration/v1/conference/?aliases__alias__contains=@
Ordering
A request for multiple objects can be ordered by field values. For example, to get the conference history ordered by start time the URI
would be:
https://<manageraddress>/api/admin/history/v1/conference/?order_by=start_time
The order can be reversed by adding a hyphen character (-) before the field name. For example, to order by descending start time so
that the most recent conferences are listed first, the URI would be:
https://<manageraddress>/api/admin/history/v1/conference/?order_by=-start_time
The fields that can be used for ordering are included at the end of the schema for each resource. If an ordering section is not present,
then ordering is not available.
Examples
The examples below assume a community name of public (this is the default value and so is insecure).