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


In all API, CSV or RSS requests, you can use an API key to be authenticated. The API key can be found on the user account edit page or in the my profile page for your account.

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

The API key argument should be given in a request header named api-key. For compatibility with older versions of the API and to allow usage with some tools that don’t support to set headers, the api_key argument can also be given in the url query string (?api_key=X) or in the 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 [oid]) are optional. Any failed call will return a status code greater than or equal 400.

Common fields are :

  • [error]

    Error description message when the request has failed.

  • [errors]

    List of errors (only in some calls).

  • [message]

    Informational message.

URL construction rules

Most of the API response data will not contain direct links or embed data, but provides a media identifier, which is a unique identifier of the video. The on-demand video ids are prefixed with the letter v, live streams by the letter l, photos groups 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:


An iframe url, containing only the player:


An iframe url, containing only the player with the sidebar hidden:


Another iframe url, containing the editor:


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 (when creating a live stream for example). Channels have a maximum recursion level of 5 (it means that a channel can have 5 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.


Player iframe API

Indices and tables