EEG / Ai-Media iCap REST API Documentation v1.0

Overview

The goal of this REST API is to provide a way for integrations to manage your iCap cloud captioning resources with Ai-Media / EEG. We recommend accessing this REST API through this load balanced multi-region entry point for the most resilient and up to date version:

https://icap.eegapis.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
  • Encoder Activity - Retrieving, information about current encoder activity
  • Shared Encoders - Retrieving encoders granted to you by other companies
  • CaptionCast - Creating, retrieving, and deleting CaptionCast definitions
  • 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
  • iCap Providers - Retrieve a list of iCap Captioning providers.
  • Email Notices - Subscribe to iCap email notices related to your account status.
  • Session Login - Login to receive a session cookie and avoid needing to send header-based authentication on each subsequent call.
  • 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.

Query Parameters

limit The maximum number of records (or page size) to load. If this parameter is used, the response will include additional fields verifying the limit, offset, and total number of available records. Note that in future versions of the API, it is likely that a default limit of 1000 records will be returned if no explicit limit is specified.
offset Use this with limit to load beyond the first limit-sized page of records.
sort By default results are sorted by current user activity (sort=online). You may instead specify sorting by the username, usertype or email fields.
sortdir By default returned results are sorted in alphabetic ascending order. Use "desc" to reverse this order.
filter Return only results that contain a partial, case insensitive match for the given string in the username field

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. Omit this parameter if creating an SSO/SAML user. Instead send parameter 'samlgroup' with value set to 'company'. Note your company must have an SSO certificate and endpoints set up with Ai-Media in advance to use SSO login flows, and that SSO login flows are currently only available for 'admin' website users.
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.

Query Parameters

limit The maximum number of records (or page size) to load. If this parameter is used, the response will include additional fields verifying the limit, offset, and total number of available records. Note that in future versions of the API, it is likely that a default limit of 1000 records will be returned if no explicit limit is specified.
offset Use this with limit to load beyond the first limit-sized page of records.
sort By default results are sorted by the access codes that have current activity (sort=online). You may instead specify sorting by the primaryencoder, username, or service number fields.
sortdir By default returned results are sorted in alphabetic ascending order. Use "desc" to reverse this order.
filter Return only results that contain a partial, case insensitive match for the given string int the accesscode field

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.

Encoder Activity

The following table provides a quick definition for retrieving encoder activity through the REST API.
Resource Description
GET /api/1.0/:company/encoderactivity

Action

Retrieves a list of caption agencies currently delivering service to the encoder, via what access code, and on what caption service.

The encoder name is taken from the credentials supplied with the request. This is most useful when using the Ai-Media iCap SDK to create a virtual encoder.

GET Parameters

:company Your company name.

GET /api/1.0/:company/encoderactivity/:encoder

Action

Retrieves a list of caption agencies currently delivering service to the :encoder, via what access code, and on what caption service.

The encoder name is taken from the credentials supplied with the request.

GET Parameters

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

denotes an optional parameter.

Shared Encoders

The following table provides a quick definition for retrieving external encoders shared with you through the REST API.
Resource Description
GET /api/1.0/:company/sharedencoders

Action

Retrieves a list of shared encoders, each of which includes a broadcaster (the company that owns the encoder) and an encoder username.

GET Parameters

:company Your company name.

denotes an optional parameter.

CaptionCast

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

Action

Retrieves list of CaptionCast definitions under :company.

GET Parameters

:company Your company name.

GET /api/1.0/:company/captioncasts/:eventcode

Action

Retrieves the specified :eventcode data under :company.

GET Parameters

:company Your company name.
:eventcode The CaptionCast eventcode you wish to fetch.

POST /api/1.0/:company/captioncasts

Action

Creates a new CaptionCast definition under :company's namespace. Returns a 201 HTTP Code on completion.
**PLEASE NOTE** CaptionCast events are a billable item. The call with return a 401 HTTP Code if your company is not set up with a paid Captioncast account.

GET Parameters

:company Your company name.

POST Parameters (JSON)

eventcode The eventcode to use for the CaptionCast event.
accesscode The accesscode to be used as the source for CaptionCast text.
banner The banner text to display to the CaptionCast users for this eventcode.

DELETE /api/1.0/:company/captioncasts/:eventcode

Action

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

GET Parameters

:company Your company name.
:eventcode The CaptionCast eventcode you wish to delete.

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
The eventlog is a general stream of user activities through either the accounts site or the live iCap transit system. The captionlog is a specific stream of encoder/captioner pairs with session start/end times that shows only when these user accounts were connected.
:filterby What you wish to filter the result by. Valid values include:
  • username
  • accesscode
"accesscode" based filtering is not valid for captionlog event types.
:value The filter value (the username if filterby is set to username, accesscode if filterby is set to accesscode). Omit this parameter if you selected "all" in filterby.
:timeframe The timeframe (in seconds) the search will go back for. (example: 86400=1 day, 604800=1 week). You are limited to one year back.

Query Parameters

limit The maximum number of records (or page size) to load. If this parameter is used, the response will include additional fields verifying the limit and offset. A default limit of 100,000 records will be returned if no explicit limit is specified. Note that for performance reasons, a total number of available log records matching the query is not calculated for cases when the number of records exceeds the limit. It is recommended to use the offset parameter to attempt to load another page of results if the number of returned results equals the limit and entries further back in time are required.
offset Use this with limit to load beyond the first limit-sized page of records.
captioningonly When set to non-zero value, use a special filter that is valid for the eventlog stream and only shows 'Start Captioning' and 'End Captioning' events.

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.

Caption Providers

Retrieves a list of iCap Captioning agencies with their iCap agency codes, full names, email and phone contacts (if provided).

Note: No authorization credentials are required in order to access this list.

Resource Description
GET /api/1.0/providers

Action

Retrieves a list of iCap Captioning agencies.

Note: If your agency's contact information is missing or incorrect, and you wish it to be included, please notify Ai-Media Support.

denotes an optional parameter.

Email Notices

Subscribe to email notices the iCap system will send about your account such as encoders going online and offline, or daily logs of caption activity

Resource Description
GET /api/1.0/:company/emailnotices/subscriptions/:emailaddr

Action

Retrieves a list of previously created email subscriptions for activites under specified :company

GET Parameters

:company Your company name.
:emailaddr Email address to filter subscription search by. Omitting this returns all subscriptions to activity in this company space.

POST /api/1.0/:company/emailnotices/subscriptions

Action

Creates a new email subscription for an activity under :company's namespace.

GET Parameters

:company Your company name.

POST Parameters (JSON)

emailaddr The email address to send the notices to
subscriptiontype Set to "DailyCaptionLog" to subscribe to a daily timestamp log of all live caption sessions in the account. Set to "AllUsers" to get notices when any username in the account connects to iCap or subsequently disconnects from iCap. Set to "AllEncoders" to only get connect/disconnect notices for encoder-type users. Set to "UserAccount" and use the useraccount parameter to get notices only related to a specific username. You can subscribe separately to any number of user names, but you can't combine individual username subscriptions with "All" style subscriptions to the same email address.
useraccount Use with the "UserAccount" subscription type to specify a username that must already exist in your account and receive connect/disconnect notices for that iCap account.

DELETE /api/1.0/:company/emailnotices/subscriptions

Action

Deletes the specified subscription under :company's namespace.

GET Parameters

:company Your company name.

Post Parameters

emailaddr The email address of the account you wish to delete.
subscriptiontype The type of the subscription to delete (see the POST for type meaning explanations)
useraccount Specific user account subscription to delete when used with "UserAccount" subscriptiontype

denotes an optional parameter.

Session Login

The Login resource provides a signed cookie that the client can use to make additional calls within the company namespace without providing authentication headers for each subsequent request. The cookie is time limited and you will be asked for authentication data again when it expires.
Resource Description
POST /api/1.0/:company/login/admin

Action

Must login with header-based authentication, will return a signed cookie that can be presented in place of header-authentication for subsequent calls until the cookie expires.

POST /api/1.0/:company/logout

Action

Removes and invalidates your cookie session.

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 .

Copyright © 2013-2022 Ai-Media and EEG Enterprises, Inc. All Rights Reserved.