Reference
This section lists the most common API calls. However if you want to access a feature of Operations Monitor through the new REST API that is not listed here, see "Reverse Engineering of API Calls".
Note:
All parameter names and options (given in round brackets, separated by vertical lines) are case sensitive.
Note:
All parameters are mandatory with all REST API calls unless marked as optional. This is not enforced by the server. For many parameters fall back values are defined. You are strongly advised not to rely on these fall back values as any software updates could break your code in the case that fall back values have been changed.
Fundamental Concepts
Please note that there are some basic principles to the new REST API that you should know in order to have a better understanding of the API:
All REST API calls are made using HTTPS. Any requests using plain HTTP will result in a HTTP/1.1 301 Moved Permanently.
All parameters of calls are transmitted as HTTP header fields.
Responses are JSON Objects.
If the API call succeeded the response will be a 200 Ok HTTP message and the success field of the response will have the value true.
If a call doesn't succeed, the response will be a 200 Ok HTTP message too. The success field of the response however will be false and there will be a field errorMsg containing a brief description of what went wrong.
Note:
In some cases instead of a 200 Ok HTTP message, a 404 type message will be returned. In this rare event instead of a JSON object a HTML string, containing an error page, will be returned. So please be sure to also check for 404, and 301 HTTP responses (see above) when checking for errors!
Often calls have a method for limiting the result set. This is done just as in the database world where you can specify from which element you want to start and how many elements you want to have returned at most.
The filtering concept that is used in getPagedCalls is also available for any other data that is being presented as a sortable grid with optional filters in Operations Monitor. For more information on how to design filters and reverse engineer the API for any other data accessible through Operations Monitor, see "Examples" and "Reverse Engineering of API Calls".
In order to get a better understanding of all these concepts please feel free to play around with the little snippets presented in the "Examples" section.
Configuration Savepoints
Note:
For security reasons, REST APIs are not stored in configuration savepoint.
Table 11-1 describes the /me/saveApplianceConfiguration savepoint object.
Table 11-1 /me/saveApplianceConfiguration
Description | Method | Parameters | Returns |
---|---|---|---|
Creates a savepoint on the server and returns the name of the savepoint. |
POST |
None. |
name Name of the save point. |
Table 11-2 describes the /me/uploadApplianceConfiguration savepoint configuration.
Table 11-2 /me/uploadApplianceConfiguration
Description | Method | Parameters | Returns |
---|---|---|---|
Uploads a savepoint to the Server and returns the name of the savepoint. |
POST |
configuration Local file name. name “configuration". |
name Name of the save point on the server. |
Table 11-3 describes the /me/downloadApplianceConfiguration savepoint object.
Table 11-3 /me/downloadApplianceConfiguration
Description | Method | Parameters | Returns |
---|---|---|---|
Downloads a previously saved or uploaded configuration savepoint. |
POST |
name Name of the savepoint to be downloaded. |
The requested file. File name is included in the content-disposition Response Header field. |
Table 11-4 describes the /me/restoreApplianceConfiguration savepoint object.
Table 11-4 /me/restoreApplianceConfiguration
Description | Method | Parameters | Returns |
---|---|---|---|
Restores a previously saved to uploaded savepoint. |
POST |
configuration Name of the savepoint to be restored. |
warnings Warnings that occurred during the restore process, separated by newline characters. |
Table 11-5 describes the /me/deleteApplianceConfiguration savepoint object.
Table 11-5 /me/deleteApplianceConfiguration
Description | Method | Parameters | Returns |
---|---|---|---|
Deletes a savepoint. |
POST |
name Name of the savepoint to be deleted. |
None. |
Table 11-6 describes the /me/listApplianceConfigurations savepoint object.
Table 11-6 /me/listApplianceConfigurations
Description | Method | Parameters | Returns |
---|---|---|---|
Gets list of save points. |
POST |
start Starting offset for the results to be returned. limit Limits the number of results to be returned. sort Column by which to sort the results (“date" | “name"). dir Whether to sort results ascending or descending (“ASC" | “DESC"). |
configurations Array with informations about the individual savepoints. totalCount Number of savepoints in total (not the number of returned savepoints). |
Calls
Table 11-7 describes the /me/getPagedCalls call object.
Table 11-7 /me/getPagedCalls
Description | Method | Parameters | Returns |
---|---|---|---|
Gets a list of calls around a given point in time or around a given call. |
POST |
filters See the filter design template and the tables below to design your own filters for the result set. If you do not want to filter the result set, please pass an empty list instead ([]). older_than Pass an ID of an element of the result set here to retrieve elements older than the given element. older_than_ts Same as the above, only here you pass the timestamp of an object, not its ID. newer_than, newer_than_ts Same as the above, just into the opposite direction. limit Limits the amount of results to be returned. |
calls Array with calls objects. See the below table for details. first_page Whether or not the returned result set is the first page of results available (true | false). last_page Whether or not the returned result set is the last page of results available (true | false). next_value When you want to retrieve the next page of results using the same parameters, use next_value for the older_than field in the request header. |
Filter Design Template
{"field":"<field>","data":{"type":"<type>","comparison":"<comparison>", "value":"<value>"}}
Where:
<field> is the name of the field that the filter applies to.
<type> is the type of the filter. Depending on the type of the field there are different filters available. See Table 11-10 for details.
<comparison> is the comparator to be used for filtering. See Table 11-10 for details.
<value> is the value to compare against in the filter. See Table 11-10 for details.
Creating a Filter for a Specific Column
To create a filter for a specific column:
Locate the <field> value for the desired column (see the Field (<field>) column in Table 11-8).
Locate the type of the column (see the Type column in Table 11-8).
Refer to Table 11-10 to see which filters are available and how to use them.
Refer to "Examples" and "Reverse Engineering of API Calls" for in depth examples on how to use getPagedCalls and how to watch network traffic to get a better understanding of the API.
Table 11-8 lists the columns and fields in the calls objects that can be filtered.
Note:
Table 11-9 lists fields, which are also part of the calls objects that cannot be filtered.
Table 11-8 Fields and Types (in alphabetical order)
Field (<field>) | Type | Column in the Calls Table |
---|---|---|
call_time |
Numeric |
Call time |
code |
Numeric |
Code |
dpc |
String |
DPC |
dst_codecs |
String |
Callee Codecs |
dst_initial_codecs |
String |
Callee Initial Codecs |
dst_ip |
IP address |
Callee IP address. For the data field of the filter, set type to ipaddr and value to the IP address string (e.g. 192.168.1.123 or 10.0.0.0/8). |
dst_ua |
String |
Callee User Agent |
dst_user |
String |
Callee |
dst_user_pref_tag |
Boolean |
Preferred Callee Number? For the data field of the filter:
|
dtmf |
Boolean |
DTMF |
egress_devs |
List |
Egress device(s) |
end_ts |
Datetime |
End timestamp |
gateway_devs |
List |
Gateway Devices |
in_devs |
List |
In devices |
ingress_devs |
List |
Ingress device(s) |
init_devs |
List |
Initiator device |
megaco_cmds |
String |
MEGACO Commands |
megaco_context_id |
String |
MEGACO Context ID |
megaco_mg_ip |
String |
MEGACO Gateway |
megaco_mgc_ip |
String |
MEGACO Gateway Controller |
megaco_termination_id |
String |
MEGACO Termination ID |
megaco_txids |
String |
MEGACO Transaction IDs |
mgcp_call_ids |
String |
MGCP Call IDs |
mgcp_capabilities |
String |
MGCP Capabilities |
mgcp_connection_ids |
String |
MGCP Connection IDs |
mgcp_mg_ip |
String |
MGCP Gateway IP |
MOSlqe_avg |
Numeric |
Avg. MOS |
MOSlqe_min |
Numeric |
Min. MOS |
nlegs |
Numeric |
Segments |
opc |
String |
OPC |
out_devs |
List |
Out devices |
pai |
String |
P-Asserted-ID |
prefix_group |
List |
Prefix Group |
q850_code |
Numeric |
Q.850 Code |
q850_state_details |
String |
Q.850 Details |
q850_state_msg |
String |
Q.850 State |
realms_recordings |
Boolean |
Media For the data field of the filter, set type to custom:streams_availability and value to false, or true depending on which you want to filter for. |
reason_hdr |
|
Reason |
rpid |
String |
Remote-Party-ID |
rtcp_delay_avg |
Numeric |
Avg RTCP delay |
rtcp_delay_max |
Numeric |
Max RTCP delay |
rtcp_streams |
Numeric |
RTCP streams |
setup_delay |
Numeric |
Setup Delay |
setup_delay_type |
List |
Setup Delay Type With this column you have two options which you can filter for. You may filter for either one, or both options:
|
setup_start_ts |
Datetime |
Start timestamp |
setup_time |
Numeric |
Setup time |
src_codecs |
String |
Caller Codecs |
src_initial_codecs |
String |
Caller Initial Codecs |
src_ip |
IP address |
Caller IP address. For the data field of the filter, set type to ipaddr and value to the IP address string (e.g. 192.168.1.123 or 10.0.0.0/8). |
src_ua |
String |
Caller User Agent |
src_user |
String |
Caller |
src_user_pref_tag |
Boolean |
Preferred Caller Number? For the data field of the filter:
|
state_details |
String |
State details |
state_msg |
List |
State Options are as follows:
You may filter for one or more of the above options. Just include the desired value(s) from the above list as Strings in the array you pass for <value>. |
term_devs |
List |
Terminator device |
Table 11-9 lists fields that are not in the above table (cannot be filtered) but are part of the calls objects:
Table 11-9 Call Object Fields that Cannot be Filtered
Field | Description |
---|---|
pid |
Process ID. |
id |
ID of the call. A call is uniquely identified through its pid and id. |
id32 |
Internal only. |
strictly_increasing |
ID which can be used for sorting call events chronologically. |
state |
Numeric representation of state. |
state_cls |
Color of state. |
end_ts |
Timestamp of when the call was finished. |
mos_cls |
Color of the mos column. |
overload |
Whether during the processing of the call a system overload occurred. |
number_prefix |
Contains a comma separated list for all the number prefixes, that the respective call is matching. |
Table 11-10 lists all available filter types. Please note that the table has been grouped by column data type (see above table) to show which filter options are available for the corresponding field type.
Table 11-10 Filter Types (grouped by column data types)
Type (<type>) | Comparators (<comparison>) | Description |
---|---|---|
String exactstring string |
None. None. |
Matches exact string. Match string. |
DateTime date
datetime datetime_utc |
lt gt eq neq leq geq (lt | gt | eq | neq | leq | geq) (lt | gt | eq | neq | leq | geq) |
less than (before given date) (<). greater than (after given date) (>). equal (on the given date) (=). not equal (not on the given date) (!=). less or equal (on or before the given date (<=). greater or equal (on or after the given date) (>=). Equals only compares dates. Equals only compares dates. Use this version if <value> is a UTC timestamp. |
Numeric numeric |
(lt | gt | eq | neq | leq | geq) |
Does the job of any first grader only slightly faster. |
List in_list list not_in_list |
None. None. None. |
Matches one value of the array given in <value>. Matches at least one element of the array given in <value>. Does not match a value of the array given in <value>. |
Table 11-11 describes the /me/getCallDetails call object.
Table 11-11 /me/getCallDetails
Description | Method | Parameters | Returns |
---|---|---|---|
After you called getPagedCalls to retrieve a list of calls you can use getCallDetails to obtain further information about a specific call. |
POST |
id ID of call as returned in the id field of a call. pid As returned in the pid field of a call. saved_id (Optional) Instead of passing the previous two IDs you can just pass this ID in case you saved this call. no_legs (true | false). |
An array with essentially the same fields as getPagedCalls but also a few additional fields:
Internal only fields:
|
Table 11-12 describes the /me/getCallMsgs call object.
Table 11-12 /me/getCallMsgs
Description | Method | Parameters | Returns |
---|---|---|---|
Returns the SIP messages associated with a given call. |
POST |
id ID of call as returned in the id field of a call. pid As returned in the pid field of a call. saved_id (Optional) Instead of passing the previous two IDs you can just pass this ID in case you saved this call. |
proto Protocol. src_ip Source IP. src_mac Source Mac. opc Source PC. dst_ip Destination IP. dst_mac Destination MAC. dpc Destination PC. ts Date and Time. method Message. ruri Details |
Table 11-13 describes the /me/getCallsTime call object.
Table 11-13 /me/getCallsTime
Description | Method | Parameters | Returns |
---|---|---|---|
Returns the current time stamp (for use in for example getPagedCalls as value for the older_than_ts parameter) and the time stamp of the latest call. |
POST |
None. |
ts_first Timestamp of the first call in the database. ts_now Current timestamp - can be used as a value for older_than_ts. For example in getPagedCalls. |
Table 11-14 describes the /me/getAvailablePcaps call object.
Table 11-14 /me/getAvailablePcaps
Description | Method | Parameters | Returns |
---|---|---|---|
Get the available pcaps and the streams available in the respective pcap. |
POST |
id ID of call as returned in the id field of a call. pid As returned in the pid field of a call. saved_id (Optional) Instead of passing the previous two IDs you can just pass this ID in case you saved this call |
available An object which contains all available recorded streams for the specified user grouped by stream type. |
Table 11-15 describes the /me/callPcap call object.
Table 11-15 /me/callPcap
Description | Method | Parameters | Returns |
---|---|---|---|
Download a pcap file for a specific call. |
POST |
id ID of call as returned in the id field of a call. pid As returned in the pid field of a call. saved_id (Optional) Instead of passing the previous two IDs you can just pass this ID in case you saved this call. filename If this is not empty it is going to be the filename of the pcap file that is retrieved from the server. streams Array which includes which stream types you would like to retrieve. Include the string "EN10MB" in the array to include signaling messages, and for every stream for which you want to retrieve the RTP payload include a string of the format: “<Media type>#<src_ip>:<src_port>#<dst_ip>:<dst_port>#<media_content_type>" Example: “MEDIA#62.220.31.225:19848#62.220.31.239:27998#rtp_full" If the above fields are not familiar please make sure to experiment with getAvailablePcaps and play around with the RTP recording feature and the save PCAP feature in the regular Operations Monitor web interface. |
The requested pcap file. |
Registrations
Table 11-16 describes the /me/getRegsPaged registrations object.
Table 11-16 /me/getRegsPaged
Description | Method | Parameters | Returns |
---|---|---|---|
Retrieves a list of registrations around a point in time or around another registration. |
POST |
None older_than Pass an ID of an element of the result set here to retrieve elements older than the given element. older_than_ts Same as the above, only here you pass the timestamp of an object- not its ID. newer_than, newer_than_ts Same as the above, just into the opposite direction. |
data Array containing all registrations of the current result set. Fields contained in data:
first_page Whether or not the returned result set is the first page of results available (true | false). last_page Whether or not the returned result set is the last page of results available (true | false). next_value When you want to retrieve the next page of results using the same parameters, use next_value for the older_than field in the request header. |
Table 11-17 describes the /me/getRegsTime registrations object.
Table 11-17 /me/getRegsTime
Description | Method | Parameters | Returns |
---|---|---|---|
Returns the current time stamp (for use in for example getPagedRegs as value for the older_than_ts parameter) and the timestamp of the latest registration. |
POST |
None. |
ts_first Timestamp of the first registration result set using the passed filters. ts_now Current timestamp- can be used as a value for older_than_ts for example in getPagedCalls. |
Table 11-18 describes the /me/getRegEvent registrations object.
Table 11-18 /me/getRegEvent
Description | Method | Parameters | Returns |
---|---|---|---|
Gets details about a registration event. |
POST |
id ID of the event for which you want to retrieve the SIP messages. |
reg Array containing the SIP messages for the specified event. |
Table 11-19 describes the /me/getRegEvMsgs registrations object.
Table 11-19 /me/getRegEvMsgs
Description | Method | Parameters | Returns |
---|---|---|---|
Gets the SIP messages for a specified event. |
POST |
id ID of the event for which you want to retrieve the SIP messages. start Starting offset for the results to be returned. limit Limits the amount of results to be returned. |
totalCount Total count of the result set - not the amount of elements returned. data Array with the requested SIP messages. |
KPI
Table 11-20 describes the /me/getCounterValues KPI object.
Table 11-20 /me/getCounterValues
Description | Method | Parameters | Returns |
---|---|---|---|
Returns counters marked as favorites and their recent values. |
POST |
None. |
counters An array containing the requested counters. |
Table 11-21 describes the /me/addOrModifyCounter KPI object.
Table 11-21 /me/addOrModifyCounter
Description | Method | Parameters | Returns |
---|---|---|---|
Add or modify a counter. |
POST |
action Whether to edit or add a counter (“add" | “edit"). snmp_export (Optional) Set this to “on" to enable snmp export, or do not use this parameter to disable snmp export. maintype Numeric representation of the counter. Use getCounterTypes to find out the main types of counters. subtype Numeric representation of the counter. Use getCounterTypes to find out the subtypes of counters. If you want to create an average counter include the three properties below:
|
id ID of the added or changed counter. |
Table 11-22 describes the /me/deleteCounter KPI object.
Table 11-22 /me/deleteCounter
Description | Method | Parameters | Returns |
---|---|---|---|
Removes a counter. |
POST |
id ID of the counter to be removed. |
None. |
Table 11-23 describes the /me/toggleSNMPExport KPI object.
Table 11-23 /me/toggleSNMPExport
Description | Method | Parameters | Returns |
---|---|---|---|
Enables or disables the SNMP export of a counter. |
POST |
ids List of counter IDs. action (‘enable' | ‘disable'). |
None. |
Table 11-24 describes the /me/getCounterRealm KPI object.
Table 11-24 /me/getCounterRealm
Description | Method | Parameters | Returns |
---|---|---|---|
Get a counter's realm. |
POST |
id ID of the counter. |
realm Realm of the given counter. |
Table 11-25 describes the /me/getCounterConfig KPI object.
Table 11-25 /me/getCounterConfig
Description | Method | Parameters | Returns |
---|---|---|---|
Retrieves the configuration of a user counter. You can modify the returned configuration and pass it to addOrModifyCounter to update/create a counter with the modified configuration. |
POST |
id ID of the user counter to be retrieved. |
data An object with the configuration fields of the desired counter:
|
Table 11-26 describes the /me/getSimpleCounters KPI object.
Table 11-26 /me/getSimpleCounters
Description | Method | Parameters | Returns |
---|---|---|---|
Gets counters which are no average counters. |
POST |
device_id Device ID of the counter. tag_id Tag ID of the counter. |
counters Object containing the following fields:
|
Table 11-27 describes the /me/getCounters KPI object.
Table 11-27 /me/getCounters
Description | Method | Parameters | Returns |
---|---|---|---|
Gets all types of counters- even if they are average counters. |
POST |
device_id Device ID of the counter. tag_id Tag ID of the counter. |
counters Object containing the following fields:
|
Table 11-28 describes the /me/counters KPI object.
Table 11-28 /me/counters
Description | Method | Parameters | Returns |
---|---|---|---|
Get all visible counter IDs. |
POST |
alias (true | false) Whether or not to include the user's aliases in the search for counters. |
counters List with IDs of visible counters. |
Table 11-29 describes the /me/getCounterTotal KPI object.
Table 11-29 /me/getCounterTotal
Description | Method | Parameters | Returns |
---|---|---|---|
Gets the current and maximum allowed amount of counters. |
POST |
None. |
total Total count of current counters. max_counters Maximum possible amount of counters. counters_lock Whether there is currently an operation on the counters active. |
Table 11-30 describes the /me/getCounterTypes KPI object.
Table 11-30 /me/getCounterTypes
Description | Method | Parameters | Returns |
---|---|---|---|
Gets the counter types with names and parameters. |
POST |
All parameters are optional:
|
List with counters, fitting the given parameters. |
Table 11-31 describes the /me/MonitorGraph KPI object.
Table 11-31 /me/MonitorGraph
Description | Method | Parameters | Returns |
---|---|---|---|
Draws and returns a counter graph. |
POST |
All parameters are optional:
|
data JSON object with the raw data in case raw_data was set to true. Else the requested image file. |