EEG iCap REST API Documentation v1.0

Overview


The goal of this REST API is to provide an alternative way to manage your iCap resources with EEG. The most and current up-to-date version of the REST API can be found at:

https://www.eegicap.com/api/

When accessing the REST API, you will be prompted to authenticate your credentials using your administrator account via HTTP Basic Authentication.
Please note that the current service expects you to POST data in JSON format.

The current version offers the following resources:

  • Users - Retrieving, creating and deleting user accounts
  • Accesscode - Retrieving, creating, and deleting accesscodes
  • Encoder Permissions - Retrieving, creating, and deleting encoder shares
  • Logs - Retrieving log data
  • Activities - Retrieving live captioner/encoder status
  • Session IDs - Retrieving past and current session IDs for a username account
  • Uptime Statistics - Retrieving past uptime statistics for a username account. Broadcast Plus Exclusive
  • System Health - Retrieving system health information related to iCap.

Users


The following table provides a quick definition for managing user accounts through the REST API.
Resource Description
GET /api/1.0/:company/users

Action

Retrieves list of users under :company.

GET Parameters

:company Your company name.

GET /api/1.0/:company/users/:username

Action

Retrieves the specified :username data under :company.

GET Parameters

:company Your company name.
:username The username of the account you wish to fetch.

POST /api/1.0/:company/users

Action

Creates a new user under :company's namespace.

GET Parameters

:company Your company name.

POST Parameters (JSON)

username The new username to be created under your :company namespace.
password The new user password.
usertype The usertype of the new user. It should be from one of the following:
  • admin
  • captioner
  • encoder
  • relay
  • monitor

DELETE /api/1.0/:company/users/:username

Action

Deletes the specified :username under :company's namespace.

GET Parameters

:company Your company name.
:username The username of the account you wish to delete.

Query Parameters

cascade By default, this call will fail if :username is listed as a primary or secondary encoder on one or more access codes. However, if you want the delete to go through anyway and have :username removed from all of its access codes, you can set this query parameter to true.

denotes an optional parameter.

Accesscodes


The following table provides a quick definition for managing accesscodes through the REST API.
Resource Description
GET /api/1.0/:company/accesscodes

Action

Retrieves list of accesscodes under :company.

GET Parameters

:company Your company name.

GET /api/1.0/:company/accesscodes/:ac

Action

Retrieves the specified :ac (accesscode) data under :company.

GET Parameters

:company Your company name.
:ac The accesscode you wish to fetch.

POST /api/1.0/:company/accesscodes

Action

Creates a new accesscode under :company's namespace. Returns a 201 HTTP Code on completion.
Use HTTP "PUT" to make changes to an existing access code. All parameters need to be included, and are overwritten, with each PUT update.

GET Parameters

:company Your company name.

POST Parameters (JSON)

accesscode The new accesscode to be created under your :company namespace.
broadcaster The company name of the owner of the primaryencoder.
primaryencoder The name of the primary encoder that will be using this accesscode.
service The service type of the new accesscode. It should be from one of the following:
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
sharedwith A list of company names that this accesscode will be shared with.
secondaryencoder

A list of secondary encoders that will be using this accesscode. Each entry must contain the following fields:

broadcaster The company name of the owner of this encoder.
encoder The name of the encoder that will be using this accesscode.

DELETE /api/1.0/:company/accesscodes/:ac

Action

Deletes the specified :ac under :company's namespace.

GET Parameters

:company Your company name.
:ac The accesscode you wish to delete.

denotes an optional parameter.

Encoder Permissions


The following table provides a quick definition for managing encoder shares through the REST API.
Resource Description
GET /api/1.0/:company/encoderpermissions

Action

Retrieves a list of encoder shares, each of which includes an encoder username under :company and a list of other companies that it is shared with. The encoders under :company that have not been shared with any other companies will not be included in the response.

GET Parameters

:company Your company name.

GET /api/1.0/:company/encoderpermissions/:encoder

Action

Retrieves the encoder share information (as defined in the previous endpoint) for the specified :encoder under :company.

GET Parameters

:company Your company name.
:encoder The encoder username under your :company to query.

POST /api/1.0/:company/encoderpermissions

Action

Shares one of the encoders under :company with a list of other companies.

GET Parameters

:company Your company name.

POST Parameters (JSON)

encoder An encoder username under your :company to share.
agencies A list of company names to share this encoder with.

DELETE /api/1.0/:company/encoderpermissions/:encoder/:agency

Action

Unshares the specified :encoder under :company from the specified :agency.

GET Parameters

:company Your company name.
:encoder The encoder username under your :company to unshare.
:agency The name of the company to unshare this encoder from.

denotes an optional parameter.

Logs


The following table provides a quick definition for retrieving logs through the REST API.
Resource Description
GET /api/1.0/:company/logs/:logtype/:filterby/:value/:timeframe

Action

Retrieves log data under specified :company.

GET Parameters

:company Your company name.
:logtype The type of log you wish to fetch. Valid values include:
  • eventlog
  • captionlog
:filterby What you wish to filter the result by. Valid values include:
  • username
  • accesscode
:value The filter value (the username if filterby is set to username, accesscode if filterby is set to accesscode).
:timeframe The timeframe (in seconds) the search will go back for. (example: 86400=1 day, 604800=1 week)

denotes an optional parameter.

Activities


The following table provides a quick definition for retrieving live captioner & encoder activities through the REST API.
Resource Description
GET /api/1.0/:company/active-encoders

Action

Retrieves the current active encoders under specified :company.

GET Parameters

:company Your company name.

GET /api/1.0/:company/active-captioners

Action

Retrieves the current active captioners under specified :company.

GET Parameters

:company Your company name.

denotes an optional parameter.

Session IDs


The following table defines functions for retrieving current or historical live session IDs for a user through the REST API.
Resource Description
GET /api/1.0/:company/sessions/:username/:epoch_start/:epoch_end

Action

Retrieves the session IDs assigned to this account (company and username) over the period of time specified by the start and end stamps. .

GET Parameters

:company Your company name.
:username The user name you are seeking session IDs for.
:epoch_start An integer timestamp using the Unix seconds-since-epoch UTC format. The earliest time you are interested in data for.
:epoch_end An integer timestamp using the Unix seconds-since-epoch UTC format. The most recent time you are interested in data for.

denotes an optional parameter.

Uptime Measurement


This feature requires a company/user iCap Broadcast Plus plan.
The following table defines functions for retrieving historical uptime information for a user through the REST API. Note that this is mostly useful for user accounts like encoders that are expected to maintain a continuous connection to iCap. Over the default period of 1 month, in typical applications an uptime expectation would be at least 99% (returned as 0.99), and may be as high as 99.99% (0.9999). Facilities often strive for "5 nines reliability" or 99.999% (0.99999), but a measurement period of several months or more is typically required for uptime figures at this level to stabilize.
Resource Description
GET /api/1.0/:company/uptime/:username/:epoch_start/:epoch_end

Action

Retrieves the communication uptime with iCap calculated for this account (company and username) over the period of time specified by the start and end stamps. Each interval of non-connectivity during the period is returned, as well as a final fractional figure. If you do not specify a start and end time, data for the last 30 days will be returned.

GET Parameters

:company Your company name.
:username The user name you are seeking uptime information for.
:epoch_start An integer timestamp using the Unix seconds-since-epoch UTC format. The earliest time you are interested in data for. Defaults to 30 days ago.
:epoch_end An integer timestamp using the Unix seconds-since-epoch UTC format. The most recent time you are interested in data for. Defaults to present time.

denotes an optional parameter.

System Health


The Health resource provides an overview of current and historical material related to iCap system health, notices, and outages.
Resource Description
GET /api/1.0/health/overview

Action

Retrieves a set of overview parameters about the current and historical system health .