User-level requests

User privilege-level requests:

Request	Purpose
POST /myconferences	Create a conference
GET /myconferences	List conferences
PUT  /myconferences/<conf_id>	Update a conference
DELETE /myconferences/<conf_id>	Cancel a conference
GET /myconferences/<conf_id>	Retrieve conference details
PUT /myconferences/<conf_id>/occurrences/<occur_id>	Modify a single occurrence of an existing repeating conference
DELETE /myconferences/<conf_id>/occurrences/<occur_id>	Cancel a single occurrence of a repeating conference
GET /myconferences/<conf_id>/occurrences/<occur_id>	Retrieve details of a single occurrence of a repeating conference
POST /invite	Send a guest invite
GET /features	Request a feature list
GET /version	Request the version

Conferences that have been created through the StarLeaf Portal cannot be managed through the API. Any attempt to do so will yield a 403 Forbidden response.

Managing conferences

Create a conference

To create a new conference, make an HTTPS POST request to:

/myconferences

The structure of the request is as follows:

{ 
  "settings": <conf_settings object: required>, 
} 	

Field	Description
settings	Settings for the conference — refer to conf_settings request object .

On success, this generates a 201 Created response with a Location header field containing the URI of the newly created conference resource. The response also includes a body having the following structure:

{ 
  "conf_id": <string>, 
  "dial_info": <conf_dial_info object> 
} 	

Field	Description
conf_id	The unique identifier for the newly created conference.
dial_info	The information required to dial into the conference — refer to conf_dial_info response object.

If the request would result in the maximum number of conferences per user or per organization being exceeded, the server generates a 507 Maximum Resource Count Exceeded response.

If the client has authenticated as an integration, the conference owner will be the integration rather than a real user.

List conferences

Use this request to:

• list the conferences owned by a user (if the client is authenticated as a real user)
• list the conferences created by the integration (if the client is authenticated as an integration)

To list conferences, make an HTTPS GET request to:

/myconferences

Used to obtain a list of unique identifiers (<conf_id>) owned by the user or integration. There is no request body. However, there is an optional query parameters that you can use in the request to limit the response to externally managed conferences:

• thisappmanaged=true: only the conferences having externally_managed set to true are returned

On success, this generates a 200 OK response with a body having the following structure:

{
    "conf_ids": [
	<string: optional>,
	<string: optional>,
	...] 
}

Field	Description
conf_ids	A list of the unique identifiers for all conferences owned by the user.

Update a conference

To update a conference, make an HTTPS PUT request to:

/myconferences/<conf_id>

where <conf_id> is the unique identifier for the conference returned when the conference was created.

Used to update an existing conference. This request can also be used to create a new conference with a <conf_id> specified by the client, in which case <conf_id> must not end in ‘@starleaf.com’.

The structure of the request is as follows:

{ 
  "settings": <conf_settings object: required> 
}	

Field	Description
settings	Settings for the conference — refer to conf_settings request object .

On success, updating an existing conference generates a 204 No Content response. Creating a new conference (with <conf_id> specified by the client) generates a 201 Created response with a Location header field containing the URI of the newly created conference resource and a body having the following structure:

{ 
  "dial_info": <conf_dial_info object> 
}	

Field	Description
dial_info	The information required to dial into the conference — refer to conf_dial_info response object.

Cancel a conference

To cancel a conference, make an HTTPS DELETE request to:

/myconferences/<conf_id>

where <conf_id> is the unique identifier for the conference returned when the conference was created. There is no request body.

On success, this generates a 204 No Content response.

Retrieve conference details

To find details about a specific conference, make an HTTPS GET request to:

/myconferences/<conf_id>

where <conf_id> is the unique identifier for the conference returned when the conference was created. There is no request body.

On success, this generates a 200 OK response with a body having the following structure:

{ 
  "settings": <conf_settings object>,
  "dial_info": <conf_dial_info object>,
  "occur_mod": [
	<string: optional>,
	<string: optional>,
	...] 
} 	

Field	Description
settings	Settings for the conference — refer to conf_settings response object .
dial_info	The information required to dial into the conference — refer to conf_dial_info response object.
occur_mod	For a repeating conference, this is a list of occurrence identifiers [<occur_id>, …] that have been modified relative to the parent conference, if any. For non-repeating conferences, this is an empty list. Each <occur_id> is the UTC start date and time of the occurrence as specified by the original parent repetition pattern, given in ISO 8601 format (including the ‘Z’ suffix to indicate UTC).

Modify a single occurrence of an existing repeating conference

To modify a single occurrence of an existing repeating conference, make an HTTPS PUT request to:

/v1/myconferences/<conf_id>/occurrences/<occur_id>

where <conf_id> is the unique identifier for the conference returned when the conference was created and <occur_id> is the occurrence identifier, which is the UTC start date and time of the occurrence as specified by the original parent repetition pattern, given in ISO 8601 format (including the ‘Z’ suffix to indicate UTC).

The structure of the request is as follows:

{ 
  "settings": <occur_settings object: required> 
}

Field	Description
settings	Settings for the occurrence — refer to occur_settings request object .

On success, this generates a 204 No Content response.

Cancel a single occurrence of a repeating conference

To cancel a single occurrence of an repeating conference, make an HTTPS DELETE request to:

/myconferences/<conf_id>/occurrences/<occur_id>

where <conf_id> is the unique identifier for the conference returned when the conference was created and <occur_id> is the occurrence identifier, which is the UTC start date and time of the occurrence as specified by the original parent repetition pattern, given in ISO 8601 format (including the ‘Z’ suffix to indicate UTC). There is no request body.

On success, this generates a 204 No Content response.

Retrieve details of a single occurrence of a repeating conference

To retrieve details of a single occurrence of a repeating conference, make an HTTPS GET request to:

/myconferences/<conf_id>/occurrences/<occur_id>

where <conf_id> is the unique identifier for the conference returned when the conference was created and <occur_id> is the occurrence identifier, which is the UTC start date and time of the occurrence as specified by the original parent repetition pattern, given in ISO 8601 format (including the ‘Z’ suffix to indicate UTC). There is no request body.

On success, this generates a 200 OK response with a body having the following structure:

{ 
  "settings": <occur_settings object> 
}	

Field	Description
settings	Settings for the occurrence — refer to occur_settings response object.

Note that the dialing information for the occurrence is not returned by this request as it is identical to that of the parent conference.

Sending guest invites

This request is only available for clients that use the challenge and response authentication method.

To send a guest invite to someone so that they can sign up to the StarLeaf Cloud service and download a software video client, make an HTTPS POST request to:

/invite

The structure of the request is as follows:

{ 
    "invitee": <string: required> 
}	

Field	Description
invitee	The email address of the person you would like to invite.

On success, this generates a 200 OK response with a body having the following structure:

{ 
   "status": invitee is callable
}

or

{ 
   "status": invite sent if possible
}

Response status	Description
invitee is callable	If this guest is logged in to Breeze, this guest is callable.
invite sent if possible	If the email address was valid, the guest has received an invite.

Requesting a feature list

This request will obtain a list of API features available on the server and enabled for the user’s or integration’s organization. Remember, that if the user has reseller privileges in the StarLeaf Cloud this request will return features for the reseller organization.

To obtain a list of API features available on the server and enabled for the organization, make an HTTPS GET request to:

/features

There is no request body.

On success, this generates a 200 OK response with a body having the following structure:

{ 
  "features": [
	<string: optional>, 
	<string: optional>,
	...]
} 	

Field	Description
features	The list of API features available on the server and enabled for the client. Some of the available features are defined in the table below (note that this is not a complete list).

 

Feature	Description
conferencing	Ability to schedule conferences.
conf_layouts	Ability to select the layout of a scheduled conference.
conf_recording	Ability to record a conference.
lync	Ability to dial into a conference using Microsoft Skype-for-Business.

Requesting the version

To obtain the software version running on the server, make an HTTPS GET request to:

/version

There is no request body.

On success, this generates a 200 OK response with a body having the following structure:

{ 
  "software_version": <string>,  
  "api_minor_version": <integer>
} 	

Field	Description
software_version	Cloud software version running on the server.
api_minor_version	API minor version running on the server.