YuJa API Overview

Authentication

Every API call requires an authentication token as a header. These tokens are generated by IT Managers/Admins and can be revoked. Authentication tokens allow for API access to a specific institution. The token is 32 characters long and can be retrieved from Admin Panel -> API.

Make sure to also save the API token after generating the token.

Token use: The token must be passed in as a header with the key “authToken” and the value as the token in every API call.

Transport and Encoding

The current API only supports the JSON data format. It is recommended to specify the application/json as the accepted header, but it is not required.

API Base URL

The base URL for the current YuJa API is {organization_subdomain}.yuja.com/services/. Organization_subdomain is assigned when the Organization account is provisioned with YuJa. For security reasons, only https access is allowed. For example, if the domain assigned to the organization is tested, then the landing page is api-testing.yuja.com and the API endpoint is api-testing.yuja.com/services.

Request Parameters

There are several ways to pass request parameters to API calls.

• As a component in the URL path. This is referred as a path parameter.
• As a part of the query string. This is referred to as a query string parameter.
• In the body of the request for non GET requests. This is referred to as a body parameter. The content must be encoded in JSON.
• In HTTP custom header. This is referred to as a header parameter.

CRUD Operations

The APIs follow the REST convention in order to realize the CREATE, READ, UPDATE, and DELETE functionalities. The following table describes the common convention used.

Operation	HTTP Method	Notes
CREATE	POST	POST is the standard way to create an object. The POST API will return the object id that is associated with the object that was created so it can be used in subsequent API calls.
READ	GET	GET retrieves information. The result can be a list or single object base on the API called.
UPDATE	PUT	PUT requires the ID of the object that needs to be updated. All update fields are optional unless specified otherwise. The fields which are set will be updated.
DELETE	DELETE	DELETE requires the ID of the object that needs to be deleted. The ID and the type of the object must match with each other.

 

Rest API Response Codes

200	OK
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

 

1 - User API Overview

Users represent all users registered in the institution. This includes Instructors, Students, and IT Managers. Users can be enrolled in courses, create captures, and request/invite/be invited to meetings. Users can also have a video collection.

1.1 - User Object Model

Variable	Type	Description
user_id	string	A unique user_id that is generated by the system.
email_address	string[255]	Email address of the user, must be unique across all users.
first_name	string[30]	First name of the user.
last_name	string[30]	Last name of the user.
login_id	string[20]	Login ID for the user.
login_password	string[20]	Login password for the user.
custom_id	string[20]	Custom ID of the user.
timezone	string	Timezone of the user.
user_type	string enum	User type. Can be one of the following: “Student”, “Instructor”, “IT Manager”.
phone_number	string[20]	Phone number of the user.

To get the user_id of the users, first make API call GET /users (Section 1.2.1). From the response, all the users’ user_id can be collected, which can be used later for other API calls.

1.2 - Main Endpoints

Method	Path	Description
GET	/users	Retrieves all of the users belonging to the organization.
GET	/users/{user_id}	Retrieves single individual user based on user_id.
POST	/users	Adds a user
PUT	/users/{user_id}	Updates a single individual user based on user_id.
DELETE	/users/{user_id}	Deletes a single user based on user_id.
GET	/users/{user_id}/groups/members	Retrieves all groups that the user has enrolled in.
GET	/users/{user_id}/groups/content_owners	Retrieves all groups that the user is content owner.

 

1.2.1 - GET /users

Returns a JSON list of objects, where each object is a user. Example URL: https://api-testing.yuja.com/services/users. No parameters are needed for this call.

Example Response:

[
{
"login_id": "loginID123",
"user_type": "IT Manager",
"user_id": "3432",
"timezone": "America/New_York",
"last_name": "doe,
"phone_number": "123-456-7890",
"first_name": "john",
"email": "john.doe@yuja.com"
},
{
"login_id": "loginID456",
"user_type": “Student",
"user_id": "44",
"timezone": "Canada/Easter",
"last_name": "doe",
"phone_number": "123-456-7890",
"first_name": "jane",
"email": "jane.doe@yuja.com"
}
]

 

1.2.2 - GET /users/{user_id}

Returns a JSON object containing the student info. Example URL: https://api-testing.yuja.com/services/users/3432

Parameters:

Name	Parameter Type	Type	Description
user_id	path parameter	string	Value should match user_id field in the GET /users call.

Example response:

{
"login_id": "loginID123",
"user_type": "IT Manager",
"user_id": "3432",
"timezone": "America/New_York",
“custom_id”: ”otherName”,
"last_name": "doe",
"phone_number": "123-456-7890",
"first_name": "john",
"email": "john.doe@yuja.com"
}

 

1.2.3 - POST /users

Creates a new user within the institution. JSON data can be composed without Optional parameters. See Section 1.1 for the details of the parameters. Example URL: https://api-testing.yuja.com/services/users

Parameters:

Name	Parameter Type	Type	Description
email_address	body parameter	string[255]	Required
first_name	body parameter	string[30]	Required
last_name	body parameter	string[30]	Required
login_id	body parameter	string[20]	Required
login_password	body parameter	string[20]	Required
custom_id	body parameter	string[20]	Optional
user_type	body parameter	string enum	Required
phone_number	body parameter	string[20]	Optional

 

This endpoint expects JSON data of this format in the body parameter:

{
"email_address": String email,
"first_name": String firstName,
"last_name": String lastName,
"login_id": String logidID,
"login_password": String password,
"custom_id": String custom_id,
"user_type": String userType,
"phone_number”: String phoneNumber
}

Example JSON data:

{
"login_id": "loginID123",
"user_type": "IT Manager",
“custom_id”: ”otherName”,
"last_name": "doe",
"phone_number": "123-456-7890",
"first_name": "john",
"email": "john.doe@yuja.com"
}

 

1.2.4 - PUT /users/{user_id}

Updates a single individual user based on {user_id}. See Section 1.1 for the details of the parameters. Example URL: https://api-testing.yuja.com/services/users/1000

Parameters:

Name	Parameter Type	Type	Description
user_id	path parameter	string	Value should match user_id field in the GET /users call.
email_address	body parameter	string[255]	Set to update email address.
first_name	body parameter	string[30]	Set to update user’s first name.
last_name	body parameter	string[30]	Set to update user’s last name.
login_password	body parameter	string[20]	Set to update user’s login password.
custom_id	body parameter	string[20]	Set to update user’s custom ID.
timezone	body parameter	string	Set to update user’s timezone.
user_type	body parameter	string enum	Set to update user’s type.
phone_number	body parameter	string[20]	Set to update user’s phone number.

 

This endpoint expects JSON data of this format the body parameter:

{
"email_address": String email,
"first_name": String firstName,
"last_name": String lastName,
"login_password": String password,
"custom_id": String custom_id,
"timezone": String timeZone,
"user_type": String userType,
"phone_number”: String phoneNumber
}

All fields are optional. Only the fields that are provided are updated.

 

1.2.5 - DELETE /users/{user_id}

Removes user of id {user_id} from the institution.

Example URL: https://api-testing.yuja.com/services/users/1000

Parameters:

Name	Parameter Type	Type	Description
user_id	path parameter	string	Value should match user_id field in the GET /users call.

 

1.2.6 - GET /users/{user_id}/groups/members

Retrieves all groups a user has enrolled in.

Example URL: https://api-testing.yuja.com/services/users/3432/groups/members

Parameters:

Name	Parameter Type	Type	Description
user_id	path parameter	string	Value should match user_id field in the GET /users call.

 

Example response:

[
{
"publish_type": "ALL",
"is_active": "1",
"group_code": "GROUP_CODE",
"group_id": 1365,
"group_name": "Name of group",
"owner_id": "2469",
"group_security": "FREE_JOIN",
"group_term": "Fall 2020"
},
{
"publish_type": "ADMIN",
"is_active": "1",
"group_code": "354",
"group_id": 121,
"group_name": "Name of group",
"owner_id": "898",
"group_security": "INVITE_ONLY",
"group_term": "Spring 2020"
}
]

 

1.2.7 - GET /users/{user_id}/groups/content_owners

Retrieves all groups that a user is the content owner of.

Example URL: https://api-testing.yuja.com/services/users/2469/groups/content_owners

Parameters:

Name	Parameter Type	Type	Description
user_id	path parameter	string	Value should match user_id field in the GET /users call.

 

Example response:

[
{
"publish_type": "ALL",
"is_active": "1",
"group_code": "GROUP_CODE",
"group_id": 1365,
"group_name": "Name of group",
"owner_id": "2469",
"group_security": "FREE_JOIN",
"group_term": "Fall 2020"
},
{
"publish_type": "ADMIN",
"is_active": "0",
"group_code": "354",
"group_id": 121,
"group_name": "Invite Only",
"owner_id": "2469",
"group_security": "INVITE_ONLY",
"group_term": "Spring 2020"
}
]

 

2 - Group API Overview

Groups represent all groups that are available in the organization. Each group has specific group security which filters the user access to that group. The group can also publish policies that only permit certain types of users to publish to those groups.

2.1 - Group Object Model

Variable	Type	Description
group_id	string	A unique group ID that is generated by the system.
owner_id	string	The ID of the owner that created the group.
group_name	string[200]	Name of the group.
group_code	string[25]	Short name for the group.
group_security	string enum	The security setting for the group. Can be one of the following values, “INVITE_ONLY”, “REQUEST_JOIN”, “SECURITY_RULE”, “FREE_JOIN”.
group_term	string[30]	The term name for this group.
publish_type	string enum	Specifies the allow users that can publish to this group. Can be one of the following values, “ALL”, “CURATE”, “ADMIN”.
is_active	boolean	Specifies whether the group is active or not.

To get the group_id of the groups, first, make API call GET /groups (Section 2.2.1). From the response, all the groups’ group_id can be collected, which can be used later for other API calls.

2.2 - Main Endpoints

Method	Path	Description
GET	/groups	Retrieves all the groups belong to the organization.
GET	/groups/{group_id}	Retrieves single individual group based on group_id.
PUT	/groups/{group_id}	Updates a single individual group based on group_id.
POST	/groups	Create a new group
DELETE	/groups/{group_id}	Delete a created group
POST	/groups/{group_id}/members/add/{user_id}	Add user to group as a member enrolled.
POST	/groups/{group_id}/content_owners/add/{user_id}	Add user to the group as an content owner
GET	/groups/{group_id}/content_owners	Retrieves all users that has content owner access to the group.
GET	/groups/{group_id}/members	Retrieves all users that has enrolled to the group.
DELETE	/groups/{group_id}/members/{user_id}	Removes user member from group. Does nothing if user not a member.
DELETE	/groups/{group_id}/content_owners/{user_id}	Removes content owner from group. Does nothing if user not a content owner.

 

2.2.1 - GET /groups

Returns a JSON list of objects, where each object is a group.

Example URL: https://api-testing.yuja.com/services/groups. No parameters are needed for this call.

Example response:

[
{
"publish_type": "CURATE",
"Is_active": “1”,
"group_code": "FALL 2020",
"group_id": 1536,
"group_name": "Name of Group",
"owner_id": 2468,
"group_security": "INVITE_ONLY"
},
{
"publish_type": "ADMIN",
"is_active": “1”,
"group_code": "",
"group_id": 1098,
"group_name": "Name of Group",
"owner_id": 1588,
"group_security": "INVITE_ONLY"
}
]

 

2.2.2 - GET /groups/{group_id}

Returns a JSON object containing the group info.

Example URL: https://api-testing.yuja.com/services/groups/1098

Parameters:

Name	Parameter Type	Type	Description
group_id	path parameter	string	Value should match group_id field in the GET /groups call.

Example response:

{
"publish_type": "ADMIN",
"is_active": “0”,
"group_code": "ECE150",
"group_id": 1098,
"group_name": "Math Class",
"owner_id": 1588,
"group_security": "INVITE_ONLY"
}

 

2.2.3 - PUT /groups/{group_id}

Edit the info of a group of id {group_id}. See Section 2.1 for the details of the parameters.

Example URL: https://api-testing.yuja.com/services/groups/1098

Parameters:

Name	Parameter Type	Type	Description
group_id	path parameter	string	Value should match group_id field in the GET /groups call.
group_name	body parameter	string[200]	Set to update group’s name.
group_code	body parameter	string[25]	Set to update group’s short name.
group_term	body parameter	string[30]	Set to update group’s custom name.
group_type	body parameter	string enum	Set to update group’s publish type.

This endpoint expects JSON data of this format the body parameter:

{
"group_name": String group_name,
"group_code": String group_code,
"group_term": String group_security,
“custom_name” : String custom_name,
"publish_type": String publish_type
}

All fields are optional. Only the fields that are provided are updated.

2.2.4 - POST /groups

Creates a new group. See Section 2.1 for the details of the parameters. Example URL: https://api-testing.yuja.com/services/groups

Name	Parameter Type	Type	Description
owner_id	body parameter	string	Required.
group_name	body parameter	string[200]	Required.
group_code	body parameter	string[25]	Required.
group_term	body parameter	string	Required.
publish_type	body parameter	string enum	Required.

This endpoint expects JSON data of this format in the body parameter:

{
"owner_id": String owner_id,
"group_name": String group_name,
"group_code": String group_code,
"group_term": String group_term,
"custom_name": String custom_name,
"publish_type": String publish_type
}

 

2.2.5 - DELETE /groups/{group_id}

Removes a group/class of id {group_id} from the institution.

Example URL: https://api-testing.yuja.com/services/groups/1098

Parameters:

Name	Parameter Type	Type	Description
group_id	path parameter	string	Value should match group_id field in the GET /groups call.

 

2.2.6 - POST /groups/{group_id}/members/add/{user_id}

Adds a user to a group as a member.

Example URL: https://api-testing.yuja.com/services/groups/1098/members/add/1000

Parameters:

Name	Parameter Type	Type	Description
group_id	path parameter	string	Value should match group_id field in the GET /groups call.
user_id	path parameter	string	Value should match user_id field in the GET /users call.

 

2.2.7 - POST /groups/{group_id}/content_owners/add/{user_id}

Adds a user to a group as a content owner.

Example URL: https://api-testing.yuja.com/services/groups/1098/content_owners/add/1000

Name	Parameter Type	Type	Description
group_id	path parameter	string	Value should match group_id field in the GET /groups call.
user_id	path parameter	string	Value should match user_id field in the GET /users call.

 

2.2.8 - GET /groups/{group_id}/content_owners

Returns a JSON list of objects, where each object is a user that is a content owner of the group with id {group_id}.

Example URL: https://api-testing.yuja.com/services/groups/1098/content_owners

Name	Parameter Type	Type	Description
group_id	path parameter	string	Value should match group_id field in the GET /groups call.

Example response:

[
{
"login_id": "loginID123",
"user_type": "IT Manager",
"user_id": "3432",
"timezone": "America/New_York",
"last_name": "doe",
"phone_number": "123-456-7890",
"first_name": "john",
"email": "john.doe@yuja.com"
},
{
"login_id": "loginID456",
"user_type": “Student",
"user_id": "44",
"timezone": "Canada/Easter",
"last_name": "doe",
"phone_number": "123-456-7890",
"first_name": "jane",
"email": "jane.doe@yuja.com"
}
]

 

2.2.9 - GET /groups/{group_id}/members

Returns a JSON list of objects, where each object is a user that is a member of the group with id {group_id}.

Example URL: https://api-testing.yuja.com/services/groups/1098/members

Parameters:

Name	Parameter Type	Type	Description
group_id	path parameter	string	Value should match group_id field in the GET /groups call.

Example response:

[
{
"login_id": "loginID123",
"user_type": "IT Manager",
"user_id": "3432",
"timezone": "America/New_York",
"last_name": "doe",
"phone_number": "123-456-7890",
"first_name": "john",
"email": "john.doe@yuja.com"
},
{
"login_id": "loginID456",
"user_type": “Student",
"user_id": "44",
"timezone": "Canada/Easter",
"last_name": "doe",
"phone_number": "123-456-7890",
"first_name": "jane",
"email": "jane.doe@yuja.com"
}
]

 

2.2.10 - DELETE /groups/{group_id}/members/{user_id}

Removes a member of id {user_id} from a group of id {group_id}.

Example URL: https://api-testing.yuja.com/services/groups/1098/members/1000

Parameters:

Name	Parameter Type	Type	Description
group_id	path parameter	string	Value should match group_id field in the GET /groups call.
user_id	path parameter	string	Value should match user_id field in the GET /users call.

 

2.2.11 - DELETE /groups/{group_id}/content_owners/{user_id}

Removes a content owner of id {user_id} from a group of id {group_id}.

Example URL: https://api-testing.yuja.com/services/groups/1098/content_owners/1000

Parameters:

Name	Parameter Type	Type	Description
group_id	path parameter	string	Value should match group_id field in the GET /groups call.
user_id	path parameter	string	Value should match user_id field in the GET /users call.

 

3 - Device API Overview

Devices represent all capture devices that is registered to the organization. Each device can be optionally given an IP in the management UI. This ID will be retrieved along with the other device IDs.

3.1 - Device Object Model

Variable	Type	Description
device_id	string	A unique id that is generated by the system.
device_type	string enum	Device type of the registered device. Can be one of the following values, “software_capture”, “hardware_capture”.
name	string[100]	The name given to the device.
access_level	string enum	Who can access this device, can be one of the following values “it_admin”, “me”, “content_owner”, “member”.
register_user_id	string	User ID that registered the device.
profile_id	string	A unique id generated by the system assigned to a profile. Note: For Hardware Appliances, set the profile_id to "-1"
session_id	string	A unique id generated by the system and assigned to a session.
_live_broadcast	boolean	Optional, for Hardware Appliances Only. Specifies whether the session is set to live stream.

 

3.2 - Main Endpoints

Method	Path	Description
GET	/devices	Retrieves all the devices belonging to the organization.
GET	/devices/{device_id}	Retrieves single individual device based on device_id.
PUT	/devices/{device_id}	Retrieves single individual device based on device_id.
POST	/devices/register	Register a device.
GET	/devices/registration/{access_id}	An alternative way to GET device information using access_id instead of the YuJa insternal device_id. Only available for device types which use an access_id.
GET	/devices/{device_id}/schedule	Retrieves all schedules associated with this device.
POST	/devices/{device_id}/profiles/create	Creates a capture profile for a device.
GET	/devices/{device_id}/preview/uploadlink	Generates upload URLs for uploading non-real-time previews for the device.
POST	/devices/session	Creates a Scheduled Session with the selected device and profile.
POST	/devices/startsession	Creates a session instantly with the specified device and profile.
GET	/devices/session/{session_id}/livestream/urls	Returns RTMP endpoints per stream to publish livestream content to.
POST	/devices/stopstation	Stops all sessions currently being recorded by the device.
POST	/devices/{device_id}/status	An endpoint for sending status and logging information to the Video Platform periodically.
GET	/devices/session/{session_id}/commands	The station will poll the Video Platform to retrieve commands for pause or stop which will be used for in-session control of an active session.
DELETE	/devices/{device_id}	Removes a session from the devices schedule.
GET	/devices/profiles/{device_id}/{login_id}	Retrieves all of a user’s profiles on a specified device.
GET	/devices/profiles/{device_id}	Retrieves all profiles on a specified device.
GET	/devices/userID/{sso}	Retrieves corresponding userID.
POST	/devices/editsession	Edits an existing session.
DELETE	/devices/{device_id}/schedules	Removes all schedules associated with this device.

 

3.2.1 - GET /devices

Returns a JSON list of objects, where each object is a device.

Parameters:

No parameters are needed for this call.

Example response:

{
{
"name": "station1",
"device_type": "software_capture",
"access_level": "it_admin",
“device_id ” : “12345”,
“register_user_id” : “user1”
},
{
"name": "station2",
"device_type": "hardware_capture",
"access_level": "me",
“device_id ” : “12346”,
“register_user_id” : “user2”
}
}

 

3.2.2 - GET /devices/{device_id}

Returns a JSON object, where the object is a device.

Parameters:

Name	Parameter Type	Type	Description
device_id	path parameter	string	Value should match device_id field in the GET /devices call.

 

Example response:

{
"name": "station2",
"device_type": "hardware_capture",
"access_level": "me",
“device_id ” : “12346”,
“register_user_id” : “user2”
}

 

3.2.3 - PUT /devices{device_id}

Update the device.

Parameters:

Name	Parameter Type	Type	Description
device_id	path parameter	string	Value should match device_id field in the GET /devices call.

 

3.2.4 - POST /devices/register

Registers a device. You may use the existing endpoint PUT /devices/{device_id} to edit the device after registration. Example URL:https://api-testing.yuja.com/services/devices/register

Parameters:

Name	Parameter Type	Type	Optional	Description
access_id	Body parameter	string[100]	Required	A unique identifier for the capture station.
display_name	Body parameter	string[100]	Required	The display name displayed to the end user.
station_type	Body parameter	string enum	Required	Specifies which third-party device is being registered (Example: "extron", "epiphan").
device_model	Body parameter	string	Optional	The device model.
firmware_version	Body parameter	string	Optional	The device's firmware version.
user_identifier	Body parameter	string	Required	An identifier for the Video Platform user which will be made the owner of the device.
user_identifier_type	Body parameter	string enum	Required	Possible values: "ID", "LOGIN", "SSO". Determines how the user_identifier parameter will be treated. ID represents the internal YuJa ID, LOGIN represents the user's login username, and SSO represents the user's SSO user identifier.
configuration	Body parameter	JSON object	Optional	Miscellaneous configuration.
contact_list	Body parameter	string	Optional	A list of users to send device notifications to. The string will be in the format of comma separated values where each value is a Video Platform internal user ID or an email.
save_folder (Upcoming)	Body parameter	string	Optional	The folder in Media Collections to save to. The path will be a relative path starting from the User's folder, not an absolute path. If not set, this will default to the default collection of the user.

 

Example request:

{
"access_id": "r0RQUYSM89TvCo9sm3AM",
"display_name" : "Device 1",
"device_model": "",
"firmware_version": "1.0",
"user_identifier": "username",
"user_identifier_type": "LOGIN",
"configuration": "",
"contact_list" :"11111, 11112, user@gmail.com",
"save_folder": "/MyMediaCollections/84fbbff5-b2bf-42ad-8b05-a5a227b0462e/6cfc190f-f7a4-4010-899d-b70456668e7c"
}

 

Example response:

{
“success”: “true”,
“error_message”: “”,
“id”: “12345”
}

 

3.2.5 - GET /devices/registration/{access_id}

An alternative way to GET device information using access_id instead of the Video Platform internal device_id. Only available for device types which use an access_id. Example URL: https://api-testing.yuja.com/services/devices/registrations/r0RQUYSM89TvCo9sm3AM

Parameters:

Name	Parameter Type	Type	Optional	Description
access_id	Path parameter	string[100]	Required	A unique identifier for the capture station.

 

Example response:

{
"name": "station1",
"device_type": "software_capture",
"access_level": "it_admin",
“device_id ” : “12345”,
“register_user_id” : “user1”
}

 

3.2.6 - GET /devices/{device_id}/schedule

Returns the details of sessions of the device between a time period.

Parameters:

Name	Parameter Type	Type	Description
device_id	path parameter	string	Value should match device_id field in the GET /devices call.
startTime	Query parameter	string	Start time of the schedule(dd-mm-yyyy)
endTime	Query parameter	string	End time of the schedule(dd-mm-yyyy)

 

Example response:

{
"session_name": "test1",
"session_description": "abc",
"length": "1:00",
“start_date” : “March 25 2019”,
“start_time” : “10:00 AM”,
“group_name” : “Course 1”,
“session_creator” : “itmanager1”,
“session_id”: “619”
}

 

3.2.7 - POST /devices/{device_id}/profiles/create

Creates a capture profile for a device. Example URL: https://api-testing.yuja.com/services/devices/{device_id}/profiles/create

Parameters: The body will contain a JSON Array where each JSON object will have the following fields.

Name	Parameter Type	Type	Optional	Description
profile_id	Body parameter	string[100]	Required	A unique identifier for the profile.
name	Body parameter	string	Required	The profile name displayed to the end user.
description	Body parameter	string	Optional	The profile description displayed to the end user.

 

Example request:

[{
profile_id: "7008c47",
name: "2-Stream Profile",
description: "A capture profile containing 1 video stream and 1 audio stream"
}, {...}]

 

Example response:

{
“success”: “true”,
“error_message”: “”
}

 

3.2.8 - GET /devices/{device_id}/preview/uploadlink (Upcoming)

Generates upload URLs for uploading non-real-time previews for the device. Within the Video Platform, the sources can be monitored which are non-real-time source previews. The video source previews are periodic image stills and the audio source previews which are short audio MP3s. This data is presented for replay in the Video Platform within the Devices tab.

Parameters:

Name	Parameter Type	Type	Optional	Description
device_id	Path parameter	integer	Required	The device id of the capture station.
source_name	Body parameter	String array	Required	The name of the source to generate upload urls for, which will be displayed to the end user.
type	Body parameter	string enum	Required	Values: audio, image.

 

Example response:

{
“success”: true,
“data”: [{
“stream_id”: “”,
“url: “”,
“key”: “”
}, {...}]
}

 

3.2.9 - POST /devices/session

Create a session.

Parameters:

Name	Parameter Type	Type	Description
start_year	Body parameter	string	Start year of the session.
start_month	Body parameter	string	Start month of the session.
start_day	Body parameter	string	Start day of the session.
start_hour	Body parameter	string	Start hour of the session.
start_minute	Body parameter	string	Start minute of the session.
duration_hour	Body parameter	string	Number of hours in the session is to last for.
duration_minute	Body parameter	string	Number of minutes in the session is to last for.
device_id	Body parameter	string	ID corresponding to the device you want to record with (get from 3.2.1).
login_id	Body parameter	string	Use sso OR login_id.
sso	Body parameter	string	Use sso OR login_id.
session_title	Body parameter	string	A title for the session.
session_description	Body parameter	string	Optional.
label_colour	Body parameter	string	Optional, must be in "#ABCDEF" format.
profile_id	Body parameter	string	An ID corresponding to the profile you want to use for the recording (profile ids found from 3.2.9). Note: For hardware devices, set the profile_id to "-1"
group_id	Body parameter	string	Optional: The group id can be found by using the get all groups request (2.2.1). Can only have group_id OR class_code not both.
class_code	Body parameter	string	Optional: The class_code is user added. Can only have group_id OR class_code not both.

 

3.2.10 - POST /devices/startsession

Start a session immediately.

Parameters:

Name	Parameter Type	Type	Description
is_live_broadcast	Body parameter	string	Use “true” to record a livestream and “false” otherwise.
group_id	Body parameter	string	Optional: The group id can be found by using the get all groups request (2.2.1). Need group_id or class_code if the session is live. Can only have group_id OR class_code not both.
class_code	Body parameter	string	Optional: The class_code is user added. Need group_id or class_code if the session is live. Can only have group_id OR class_code not both.
duration_minute	Body parameter	string	The duration in minutes of the recording.
device_id	Body parameter	string	The id of the recording device can be found with (3.2.1).
login_id	Body parameter	string	Use sso OR login_id.
sso	Body parameter	string	Use sso OR login_id.
session_title	Body parameter	string	Title of the session
session_description	Body parameter	string	Optional description for the session.
profile_id	Body parameter	string	Profile ID can be found with 3.2.9. Note: For hardware devices, set the profile_id to "-1"

 

3.2.11 - GET /devices/session/{session_id}/livestream/urls (Upcoming)

Returns RTMP endpoints per stream to publish livestream content to.

Parameters:

Name	Parameter Type	Type	Optional	Description
session_id	Path parameter	integer	Required	The session id of the capture session.

 

Example response:

{
“success”: true,
“urls”: [...] // One URL per stream
}

 

3.2.12 - POST /devices/stopstation

Stop a session immediately.

Parameters:

Name	Parameter Type	Type	Description
device_id	Body parameter	string	The id of the recording device can be found with (3.2.1).
login_id	Body parameter	string	Login.

 

3.2.13 - POST /devices/{device_id}/status (Upcoming)

An endpoint for sending status and logging information to the Video Platform periodically. This comprises our audit logs, error logs and alerts such as low-microphone (input audio) alerts.

Parameters:

Name	Parameter Type	Type	Optional	Description
device_id	Path parameter	integer	Required	The device id of the Capture Station.
timestamp	Body parameter	Timestamp	Required	A timestamp corresponding to when the event occurred.
type	Body parameter	string	Required	Values: status, alert, error.
content	Body parameter	integer	Optional	The Device status (uploading, connected, streaming, disconnected), content of the alert, or error logs, depending on the type parameter.

 

Example response:

{
“success”: true
}

 

3.2.14 - GET /devices/session/{session_id}/commands (Upcoming)

The station will poll the Video Platform to retrieve commands for pause or stop commands which will be used for in-session control of an active session. The polling interval in the middle of a recording session will be at a higher frequency compared to when it is on standby. Maximum polling frequency should not exceed once every 10 seconds.

Parameters:

Name	Parameter Type	Type	Optional	Description
session_id	Path parameter	integer	Required	The session id of the session.

 

response:

Name	Type	Description
command	string	do-nothing, pause, stop.

 

3.2.15 - DELETE /devices/{device_id}

Delete a scheduled session.

Parameters:

Name	Parameter Type	Type	Description
device_id	Path parameter	string	The Device ID can be found by (3.2.4).

 

3.2.16 - GET /devices/profiles/{device_id}/{login_id}

Get the profiles of a specific user with a specific device.

Parameters:

Name	Parameter Type	Type	Description
device_id	Body parameter	string	The id of the recording device can be found with (3.2.1).
login_id	Body parameter	string	Login of the user with the profile.

 

Example response:

{
"profiles":[
{
"profile_name": "rylmao",
"profile_id": "1150"
},
{
"profile_name": "notlive",
"profile_id": "1155"
},
{
"profile_name": "liveoncesource",
"profile_id": "1160"
},
{ "profile_name": "allofthem3sources",
"profile_id": "1164"
},
{
"profile_name": "Audio Only",
"profile_id": "1173"
},
{
"profile_name": "Screen Only",
"profile_id": "1176"
}
]
}

 

3.2.17 - GET /devices/profiles/{device_id}

Get the profiles of a specific user with a specific device.

Parameters:

Name	Parameter Type	Type	Description
device_id	Body parameter	string	The id of the recording device can be found with (3.2.1).

 

Example response:

{
"profiles": [
{
"profile_name":"Me",
"owner_name":"test",
"profile_id":"1415",
"owner_id":"userID"
},
{
"profile_name":"Fake",
"owner_name":"firstName LastName",
"profile_id":"1524",
"owner_id":"test0000"
},
{
"profile_name":"def",
"owner_name":"firstName LastName",
"profile_id":"1646",
"owner_id":"test0000"
},
{
"profile_name":"here",
"owner_name":"test 001",
"profile_id":"1647",
"owner_id":"test001"
}
]
}

 

3.2.18 - GET /devices/userID/{sso}

Retrieve corresponding userID.

Parameters:

Name	Parameter Type	Type	Description
sso	Body parameter	string	Can be retrieved from 3.2.4.

 

Example response:

testuser

 

3.2.19 - POST /devices/editsession

Update a session with given parameters.

Parameters:

Name	Parameter Type	Type	Description
device_id	Body parameter	string	Can be retrieved from 3.2.4.
start_year	Body parameter	string	Optional: Start year of the session.
start_month	Body parameter	string	Optional: Start month of the session.
start_day	Body parameter	string	Optional: Start day of the session.
start_hour	Body parameter	string	Optional: Start hour of the session.
start_minute	Body parameter	string	Optional: Start minute of the session.
duration_hour	Body parameter	string	Optional: Number of hours in the session is to last for.
duration_minute	Body parameter	string	Optional: Number of minutes the session will last for.
station_id	Body parameter	string	Optional: ID corresponding to the device you want to record with (get from 3.2.1).
login_id	Body parameter	string	Optional: Use sso OR login_id.
sso	Body parameter	string	Optional: Use sso OR login_id.
session_title	Body parameter	string	Optional: A title for the session.
session_description	Body parameter	string	Optional: A description.
label_colour	Body parameter	string	Optional, must be in "#ABCDEF" format.
profile_id	Body parameter	string	Optional: An ID corresponding to the profile you want to use for the recording (profile ids found from 3.2.9).
group_id	Body parameter	string	Optional: The group id can be found by using the get all groups request (2.2.1). Can only have group_id OR class_code not both.
class_code	Body parameter	string	Optional: The class_code is user added. Can only have group_id OR class_code not both.

 

3.2.20 - DELETE /{device_id}/schedules

Delete all scheduled sessions associated with the device.

Parameters:

Name	Parameter Type	Type	Description
device_id	Path parameter	string	The Device ID can be found by (3.2.4).

 

4 - Media API Overview

Media​ represents all assets in the institution. This includes audio files, video files, and other documents.

4.1 - Media Object Model

Variable	Type	Description
login_id	string	Login ID for the user.
group_id	string	An unique group ID that is generated by the system.
title	string	Title of uploaded video.
file_key	string	Key returned by the system to upload a file.
description	string	Description of uploaded video.
video_id	string	An unique video ID that is generated by the system.
old_video_id	string	Video id of video to be replaced.
new_video_id	string	Video id of the video after replacement.
folder_id	string	An unique folder ID that is generated by the system.

 

4.2 - Main Endpoints

Variable	Type	Description
GET	/media/createuploadlink	Retrieves an upload link and file_key to upload a media file.
POST	/media/upload/video	Uploads a video detail.
POST	/media/publish/video	Publish a video in a course.
POST	/media/replace/video	Replace a video.
GET	/media/video/group/{group_id}	Retrieves videos published in a course.
GET	/media/video/directlink/{video_id}	Retrieves direct link and embed code of a video.
GET	/media/retrievebranding	Retrieve institute media player branding
PUT	/media/updatebranding	Update institute media player branding
GET	/media/retrieveuserassets/{login_id}	Retrieve the assets of user (folders, video file, other documents)
GET	/media/retrieveuserassets/{folder_id}	Retrieve the the assets contained in a folder
POST	/media/upload/session/{session_id}/createlinks	Generate upload links to upload recordings of the session
POST	/media/upload/session/{session_id}	Signals that uploading the recording to the S3 URLs are completed and that video processing should commence

 

4.2.1 - GET /createuploadlink

Return a JSON object which contains the upload link and file_key. To upload the video to S3 make a HTTP PUT request using the returned upload link as the target and attach the video file.

Parameters:

No parameters are needed for this call.

Example response:

[
{
​"url​": "<upload_link>",
"​key​": "<key>"
}
]

 

4.2.2 - POST /upload/video/

Upload a video in media library of a user with the matching login_id of body parameter.

Parameters:

Name	Parameter Type	Type	Description
login_id	Body parameter	string	Required.
title	Body parameter	string	Required.
file_key	Body parameter	string	Required, value should match “key” field in the response field of GET /createuploadlink call.
description	Body parameter	string	Optional.

 

4.2.3 - POST /publish/video/

Publish a video owned by user with login_id in a group with matching group_id of body parameter.

Parameters:

Name	Parameter Type	Type	Description
login_id	Body parameter	string	Required.
class_id	Body parameter	string	Required.
video_id	Body parameter	string	Required.

 

4.2.4 - GET /video/group/{group_id}

Returns a JSON object containing the video details of the class.

Parameters:

Name	Parameter Type	Type	Description
group_id	Path parameter	string	Value should match group_id field in the GET /groups call.

 

Example response:

{
"description": " uploaded by abcd",
"title": "avi_test1",
"video_id": "67890"
},
{
"description": " uploaded by pqrs",
"title": "flv_test1",
"video_id": "67891"
}

 

4.2.5 - GET /video/directlink/{video_id}

Returns a JSON object containing the direct link and embed code of a video.

Parameters:

Name	Parameter Type	Type	Description
video_id	Path parameter	string	Value should match video_id field in the GET /video/group/{group_id} call.

 

Example response:

{
"​directlink​": "<Direct link to the video>",
"​embedcode​": "<The embedded code for the video>"
}

 

4.2.6 - POST /replace/video/

Replace a video owned by user with login_id by another video.

Parameters:

Name	Parameter Type	Type	Description
login_id	Body parameter	string	Required.
old_video_id	Body parameter	string	Required.
new_video_id	Body parameter	string	Required.

 

4.2.7 - GET /retrievebranding

Returns a JSON object containing the media player branding details of the organization.

Parameters:

No parameters are required for this call.

 

Example response:

{
"button_color": "#ffffff",
"setting_menu_color": "#011100",
"sidebar_color": "#ABCDEF",
"setting_text_color": "#ffffff"
}

 

4.2.8 - PUT /updatebranding/

Update media player branding details of the organization.

Parameters:

Name	Parameter Type	Type	Description
button_color	Body parameter	string	Optional
setting_menu_color	Body parameter	string	Optional
sidebar_color	Body parameter	string	Optional
setting_text_color	Body parameter	string	Optional

 

4.2.9 - GET /retrieveuserassets/{login_id}

Return a JSON object containing the video details of the class.

Name	Parameter Type	Type	Description
login_id	Body parameter	string	Required.

 

Example response:

{
{
"Asset_type": "Folder",
"folder_id": 45621,
"title": "New Folder"
},
{
"Asset_type": "Video File",
"title": "Hello World",
"video_id": 12345
}
}

 

4.2.10 - POST /media/upload/session/{session_id}/createlinks

Generates upload links to upload recordings of the session.

Parameters:

Name	Parameter Type	Type	Optional	Description
session_id	Path parameter	integer	Required	The id of the session to associate the recording with. This controls the title, description, save location of the recording within the Video Platform and the owner of the recording.
video_sources	Body parameter	JSON Array	Required	See the video_sources fields table.
pause_timestamps	Body parameter	JSON Array	Required	See the pause_timestamps fields table.

 

video_sources fields:

Name	Parameter Type	Type	Optional	Description
stream_id	Body parameter	string	Required	An identifier for the stream.
stream_type	Body parameter	string enum	Optional	Possible values: videoCapture, audioCapture, screenCapture.

 

pause_timestamps fields:

Name	Parameter Type	Type	Optional	Description
pause_timestamp	Body parameter	long	Required	A timestamp corresponding to when the session was paused, in milliseconds.
resume_timestamp	Body parameter	long	Required	A timestamp corresponding to when the session was resumed, in milliseconds.

 

Example request:

{
"video_sources": [{
"stream_type": "videoCapture",
"stream_id": "Gv9U5qvNpR"
},{
"stream_type": "screenCapture",
"stream_id": "vKYrIkpqp2",
}],
"pause_timestamps": [{
"pause_timestamp": 5000,
"resume_timestamp": 10000
}]
}

 

Example response:

{
upload_urls: [
{
stream_id: string,
url: string
}, {...}]
}

 

4.2.11 - POST /media/upload/session/{session_id}

Signals that uploading the recording to the S3 URLs are completed and that video processing should commence. Example URL: https://api-testing.yuja.com/services/media/upload/session/1234

Parameters:

Name	Parameter Type	Type	Optional	Description
session_id	Path parameter	integer	Required	The ID of the session to associate the recording with.

 

Example response:

{
“success”: true
}

 

5 - Analytic API Overview

Media​ represents all assets in the institution. This includes audio files, video files, and other documents.

5.1 - Analytic Object Model

Variable	Type	Description
group_id	string	An unique class ID that is generated by the system.

 

5.2 - Main Endpoints

Method	Path	Description
GET	/report/bandwidth/{group_id}	Retrieves bandwidth report of the group.
GET	/report/storage/{group_id}	Retrieves storage report of the group.
GET	/report/videoview/{group_id}	Retrieves video view report of the group.
GET	/report/visitors	Retrieves visitor view report of the institution.

 

5.2.1 - GET /report/bandwidth/{group_id}

Returns a file containing bandwidth usage details of a group.

Parameters:

Name	Parameter Type	Type	Description
group_id	Path parameter	string	Value should match group_id field in the GET /groups call.

 

5.2.2 - GET /report/storage/{group_id}

Returns a file containing storage usage details of a group.

Parameters:

Name	Parameter Type	Type	Description
group_id	Path parameter	string	Value should match group_id field in the GET /groups call.

 

5.2.3 - GET /report/videoview/{group_id}

Returns a file containing video view details of a group.

Parameters:

Name	Parameter Type	Type	Description
group_id	Path parameter	string	Value should match group_id field in the GET /groups call.

 

5.2.4 - GET /report/visitors

Returns a file containing visitor details of the institute.

Parameters:

No parameters are required for this call.