ACR1000A-CTL API
ServSwitch™ iPATH Manager API
Application Programming Interface (API) Manual
Customer
Support
Information
Order toll-free in the U.S.: Call 877-877-BBOX (outside U.S. call 724-746-5500)
FREE technical support 24 hours a day, 7 days a week: Call 724-746-5500 or fax 724-746-0746
Mailing address: Black Box Corporation, 1000 Park Drive, Lawrence, PA 15055-1018
Web site: w ww.blackbox.com • E-mail: info @blackbox.com
724-746-5500 | blackbox.com
ServSwitch iPATH Manager API Documentation
Table of Contents
Methods
l o g i n ...............................................................................................................................................................................3
logout ...............................................................................................................................................................................4
get_devices ...........................................................................................................................................................................5
get_channels ......................................................................................................................................................................... 8
get_presets............................................................................................................................................................................9
connect_channel ................................................................................................................................................................. 11
connect_preset .................................................................................................................................................................... 12
disconnect_channel ............................................................................................................................................................. 13
disconnect_preset ............................................................................................................................................................... 13
Page 2
We‘re here to help! If you have any questions about your application
or our products, contact Black Box Tech Support at 724 -746-5500
or go to blackbox.com and click on “Talk to Black Box.”
You’ll be live with one of our technical experts in less than 30 seconds.
724-746-5500 | blackbox.com
ServSwitch iPATH Manager API Documentation
API Documentation
API version: 2
Changelog
v2 (IPATH v2.3) - added get_devices, get_channels, connect_channel, disconnect_channel. Updated version compatibility
information.
v1 (IPATH v1.3) - added login, logout, get_presets, connect_preset, disconnect_ preset
Methods
login
logout
get_devices
get_channels
get_presets
connect_channel
connect_preset
disconnect_channel
disconnect_preset
login
This method was last updated in API version 1, and is compatible with API requests from version 1 onwards.
The API will require a valid IPATH user's login credentials to be presented in the first request. The API will return an authentication
code, which must be passed in all future requests. This authentication code can be re-used until a logout request is made, at
which point the authentication code will no longer be valid.
The concept of an “anonymous user” can apply to the API. If no login username and password are provided, the API will return
an authentication token for the anonymous user (either the same one as for the OSD, or else an “anonymous API user” account
can be created).
Input parameters:
- username
- password
- v (the IPATH API version this request is designed for)
Output values:
- timestamp - the current server time
- version - the current API version number
- token - an authentication code for future API requests
- success
NOTE: login examples are on the next page.
724-746-5500 | blackbox.com
Page 3
724-746-5500 | blackbox.com
ServSwitch iPATH Manager API Documentation
Examples
Input:
/api/?v=1&method=login&username=xxxxx&password=xxxxx
Output:
<api_response>
<version>1</version>
<timest amp>2012-12-14 12:12:12< /tim esta mp>
<success>1</success>
<token>5cf494a71c29e9465a57a81e0a2d602c< /token>
</api_response>
or
<api_response>
<version>1</version>
<timest amp>2012-12-14 12:12:12< /tim esta mp>
<success> 0</success>
<errors>
<error>
<code>2</code>
<msg>Invalid username or password</msg>
</error>
</errors>
</api_response>
logout
This method was last updated in API version 1 and is compatible with API requests from version 1 onwards.
The authentication token provided by the login function can be used until the logout function is called.
Input parameters:
- token
- v (the IPATH API version this request is designed for)
Output values:
- timestamp - the current server time
- success - 0 = fail, 1 = success
Examples
Input:
/api/?method=logout&token=xxxxx&v=1
Output:
<api_response>
<version>1</version>
< tim estamp>2011-02- 04 15:24 :15< /t ime >
<success>1</success>
s</api_response>
Page 4
724-746-5500 | blackbox.com
ServSwitch iPATH Manager API Documentation
or
<api_response>
<version>1</version>
<timest amp>2012-12-12 12:12:12</timestamp>
<success> 0</success>
<errors>
<error>
<code>3</code>
<msg>Error logging out (you may already have logged out)</msg>
</error>
</errors>
</api_response>
get_devices
This method was last updated in API version 2 and is compatible with API requests from version 2 onwards.
This function returns a list of devices.
Input parameters:
- token
- v (the IPATH API version this request is designed for)
- device_type ('rx' = receivers, 'tx' = transmitters. Default = 'rx')
- filter_d_name (Optional. Device name search string)
- filter_d_description (Optional. Device description search string)
- filter_d_location (Optional. Device location search string)
- sort (Optional. Sort results by 'name'/'description'/'location'. Default = 'name')
- sort_dir (Optional. Sort direction for results 'asc'/'desc'. Default = 'asc')
- status (Optional. '','outdated_iPATH_ip','rebooting','offline','outdated_firmware','invalid_backup_firmware','rebooting','upgrading'
- show_all (Optional. If set and not blank, shows all receivers, not just those the logged-in user is permitted to use)
- page (page number to start showing results for, default = 1)
- results_per_page (number of results per page, default = 1000)
Output values:
- version - the current API version number
- timestamp - the current server time
- success
- page (page number)
- results_per_page (number of results per page, default = unlimited)
- total_devices - the total number of devices
- count_devices - the number of devices on this page
- for each device:
- attribute: item (e.g. 17th device)
- d_id (device id)
- d_mac_address (device MAC address)
- d_name (device name)
- d_description (device description)
- d_location (device location)
- d_online (0 = offline, 1 = online, 2 = rebooting, 3 = factory_resetting, 4 = firmware_upgrading, 6 = running backup
firmware)
- d_type (rx, tx)
724-746-5500 | blackbox.com
Page 5
Loading...