HTTP Calls

---

This page lists the HTTP calls that make up the API:

• Make a New Share Session Request
• Stop an Active Share Session
• Retrieve Share Session Information
• Retrieve Share Sessions
• Retrieve Recent Share Sessions

Make a New Share Session Request

---

Make this call to create a share session on the Screenleap server. The request will return a screenShareData JSON object that you can use to start the presenter app.

Request

Sample Request

curl -H "accountid:<accountid>" -H "authtoken:<authtoken>" -X POST https://api.screenleap.com/v2/screen-shares

import java.io.BufferedReader; import java.io.InputStreamReader; import java.net.HttpURLConnection; import java.net.URL; import org.json.JSONObject; URL url = new URL("https://api.screenleap.com/v2/screen-shares"); HttpURLConnection conn = (HttpURLConnection) url.openConnection(); conn.setRequestMethod("POST"); conn.setRequestProperty("accountid", "<accountid>"); conn.setRequestProperty("authtoken", "<authtoken>"); conn.connect(); BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream())); StringBuilder buf = new StringBuilder(); String line; while ((line = rd.readLine()) != null) buf.append(line); rd.close(); JSONObject screenShareData = new JSONObject(buf.toString());

$url = 'https://api.screenleap.com/v2/screen-shares'; $ch = curl_init($url); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_HTTPHEADER, array('authtoken:<authtoken>')); curl_setopt($ch, CURLOPT_POSTFIELDS, 'accountid=<accountid>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Whether you need the following line depends on your curl configuration. curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); $screenShareData = curl_exec($ch); curl_close($ch);

import simplejson import urllib2 headers = {'accountid': '<accountid>', 'authtoken': '<authtoken>'} req = urllib2.Request('https://api.screenleap.com/v2/screen-shares', data={}, headers=headers) res = urllib2.urlopen(req) screenShareData = simplejson.loads(res.read())

require 'json' require 'net/http' require 'uri' uri = URI.parse('https://api.screenleap.com/v2/screen-shares') req = Net::HTTP::Post.new(uri.path, initheader = {'accountid' => '<accountid>', 'authtoken' => '<authtoken>'}) http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true res = http.request(req) screenShareData = JSON.parse(res.body)

Response

---

A successful request will return a response with 200 status code and a JSON object. You will pass this JSON object to the screenleap.startSharing call to start the presenter app. The JSON object also includes a viewerUrl that you will be used for integrating the viewer.

See Error Responses for information on how to handle a failed request.

Stop an Active Share Session

---

Users can end their share session on their own by clicking the stop button or closing the console. There will likely be occasions, however, where you want to force the share session to close programmatically.

For example, if you have used the Screenleap API to integrate screen sharing into a web-based conference call application, you might choose to automatically stop the share session when the user clicks the button to end a call.

Request

The request URL must include the screenShareCode, which identifies the share session to stop. The request must be made using HTTPS. The accountid and authtoken must be provided for authentication.

Response

HTTP status codes are used to indicate the result of the request:

200 - OK	The message was sent to the share session successfully. When the presenter app closes, the screenleap.onScreenShareEnd JavaScript will be triggered, just as it is when a user clicks the stop button.
401 - Unauthorized	The provided credential was missing or incorrect. See Authentication.
403 - Forbidden	You are attempting to access a share session that you did not create through the Screenleap API. Check your share code.
404 - Not Found	The share code that you are trying to stop does not exist or has already ended.

Retrieve Share Session Information

---

This call retrieves information about the specified share session.

Request

The request URL must include the screenShareCode, which identifies the share session to retrieve.

Response

HTTP status codes are used to indicate the result of the request:

200 - OK	The request was made successfully. The response will contain information about the share session in JSON format.
401 - Unauthorized	The provided credential was missing or incorrect. See Authentication.

If the request is successful, the response will contain JSON content, as described below.

Retrieve Share Sessions

---

This call retrieves information for successful share sessions that match the specified criteria. A successful share session is one to which both the presenter and one or more viewers connect. Recently completed share sessions are not included. Only the first 1000 results matching the criteria are returned.

No paging is supported. If you receive 10,000 results in the response, you can retrieve the next 10,000 results by setting startedAfter to the start time of the last result in the previous query.

Please see below for the call to retrieve recently completed share sessions and share sessions that are currently active.

Request

The request can be customized by adding optional query string parameters:

startedBefore	The start time (in milliseconds from epoch time) to be used as a filter. Only share sessions that started before this time will be returned.
startedAfter	The time (in milliseconds from epoch time) to be used as a filter. Only share sessions that started after this time will be returned.
endedBefore	The end time (in milliseconds from epoch time) to be used as a filter. Only share sessions that ended before this time will be returned.
endedAfter	The time (in milliseconds from epoch time) to be used as a filter. Only share sessions that ended after this time will be returned.
dateFormat	Optional. The format for the passed in dates, whose pattern conforms with Java's SimpleDateFormat. If not specified, the dates passed in can be in milliseconds from epoch time or one of the following default formats: "dd/MM/yy", "dd/MM/yy HH:mm:ss z".
externalId	The external ID to be used as a filter. Only share sessions that were created with this value as the externalId will be returned.

Response

HTTP status codes are used to indicate the result of the request:

200 - OK	The request was made successfully. The response will contain the share sessions in JSON format.
401 - Unauthorized	The provided credential was missing or incorrect. See Authentication.

If the request is successful, the response will contain a JSON array of share session data, as described below.

Retrieve Recent Share Sessions

---

This call retrieves information for the recent share sessions on the account. This includes share sessions that are still waiting for a presenter to connect, currently active, or recently ended (within the last 5 minutes).

Request

Response

HTTP status codes are used to indicate the result of the request:

200 - OK	The request was made successfully. The response will contain the share sessions in JSON format.
401 - Unauthorized	The provided credential was missing or incorrect. See Authentication.

If the request is successful, the response will contain a JSON array of share session data, as described below.

Share Session JSON

---

The share session JSON objects returned to the above GET requests may include the following elements:

• sessionId: The 9-digit share code assigned to this share session.
• dateCreated: The time (in milliseconds from epoch time) at which the share was created.
• accountId: The Screenleap API account id which was used to create this share session.
• externalId: The external ID which was assigned to this share session, if any.
• isSecure: A boolean signifying whether SSL was used for this share session.
• showScreenleapBranding: A boolean signifying whether Screenleap branding was used for this share session.
• isActive: For recent shares, true for shares to which both presenter and viewer have connected, but which have not ended yet. Note that there can be a delay of several minutes after a share ends before the isActive flag gets reset to false. This HTTP request should not be relied upon for realtime information; the JavaScript callback functions and Webhook URL should be used for that purpose.
• startTime: The time (in milliseconds from epoch time) at which the share started.
• endTime: The time (in milliseconds from epoch time) at which the share ended.
• totalViewers: The number of viewers who connected to the share before it ended.
• userMinutes: For successful shares that have ended. This includes the sum of minutes each participant was in the share session (from first connection to last disconnection).
• costInCents: For successful shares that have ended, the total cost for this share, in cents.
• title: The custom title that was used for this share, if any.
• apiCallbackUrl: The URL to which Screenleap will post server-to-server callbacks on share start and end, if any. The Screenleap servers will make a POST request and the content will be of type "application/json".
• participants: A JSON array of information about the participants (presenter and viewer(s)) on this share. Each participant JSON object may include the following elements:
  • participantId: The 6-digit code assigned to this participant for this share session.
  • externalId: The external ID which was assigned to this viewer, if any.
  • userAgent: The user agent for this participant's browser connection.
  • sharingStartTime: The time (in milliseconds from epoch time) at which this participant first joined the active share.
  • sharingEndTime: The time (in milliseconds from epoch time) at which this participant last left the active share.
  • durationInMinutes: The number of minutes this participant was connected to the active share. Contributes to the share session userMinutes
  • isPresenter: A boolean signifying whether this participant was the presenter (true) or a viewer (false).