Welcome to the Nudgis API documentation

This document specifies the Nudgis API; a reference python-based client is available here: https://github.com/UbiCastTeam/mediaserver-client

Authentication

In all requests, use the api_key argument of the associated user account, which you can find on the user account edit page or in the “my profil” page for your account.

Example key: sVcQ7-3nvj2-8MsqQ-7UFTj-GbpVE

If the used api key is the master API key, an extra argument named “username” can be passed to the call to use user matching username rights.

The api_key argument should be given in the url (?api_key=X) for GET requests and in data (api_key=X) for POST requests.

Data encoding

All request data should be encoded using application/x-www-form-urlencoded or multipart/form-data when some files are sent. All responses data are encoded using UTF-8.

Data formatting

All response data is formatted as json. All requests are either HTTP GET or POST. In this documentation, arguments between brackets (like [api_key]) are optional.

Common fields are :

  • success
    true or false
  • [error]
    Error description message
  • [errors]
    List of errors (only in some annotation-related calls; if present, the “error” field is not present)
  • [message]
    Informational message

URL construction rules

Most of the API response data will not contain direct links or embed data, but provides a media_id, which is a unique identifier of the video; on-demand video ids are prefixed with the letter “v”, live streams by the letter “l”, photos by the letter “p”, and channels by the letter “c”.

For instance, the video at: https://ubicast.tv/videos/rich-media-ubicast/ has the identifier v1255eaa4b0c7aw3qdha; it allows to build the following urls:

A permanent url pointing to the media:
http://ubicast.tv/permalink/v1255eaa4b0c7aw3qdha/
An iframe url, containing only the player:
http://ubicast.tv/permalink/v1255eaa4b0c7aw3qdha/iframe/
An iframe url, containing only the player with the sidebar hidden:
http://ubicast.tv/permalink/v1255eaa4b0c7aw3qdha/iframe/player/
Another iframe url, containing the editor:
http://ubicast.tv/edit/iframe/v1255eaa4b0c7aw3qdha/

Note that the string “rich-media-ubicast” is called the slug, and can be edited by the users.

Channels identifiers

Throughout this documentation, “channel” is used to target a specific channel (e.g. when creating a live stream). Channels have a maximum recursion level of 500 (it means that a channel can have 500 parents at most).

This argument can take the following values:

  • title (e.g. “Room 3”)
    The channel with the slug matching to the “slugified” title (“room-3” for the example) will be picked or created if not found. The channel will be first searched by slug (“slugified” title) and then by title. If several channels have the same title and no slug matches the “slugified” title, a random one among results will be picked.
  • c1251427e17b7o2plfgw or mscid-c1251427e17b7o2plfgw
    The unique identifier of the channel (20 characters beginning with “c” and containing only letters and digits), see previous section.
  • mscpath-Main channel title/Sub channel title/Test channel title
    The suffix is parsed and splitted on “/” (hence, this character should not be used in the channel titles), and defines the path of the channels which will be recursively created if needed. The channels will be first searched by slug (“slugified” title) and then by title. If several channels have the same title and no slug matches the “slugified” title, a random one among results will be picked.
  • mscref-12345
    The suffix is an external reference field, used for special integration purposes.
  • mscspeaker
    Used to target speaker’s personal channel. The “speaker_email” and/or the “speaker_id” fields should be filled in metadata. If the speaker’s account does not have the permission to have a personal channel or if the speaker’s information are not given, the default channel will be used.

Contents

Player iframe API

Indices and tables