API

HTTP Calls

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

Authentication

All API requests must include a valid accountid. You choose your account ID when you sign up for a developer account. The account ID may be included in your API requests as either a request header or a query string parameter.

In addition to the account ID, all API requests must include a valid authtoken, which should be passed as a request header.

Requests

Screenleap offers a REST-style API that uses JSON for serialization. API calls require the use of the correct HTTP request method (GET/PUT/POST/DELETE). Calls without the correct HTTP method will return with an error.

All requests that require passing in the authtoken must use SSL. Requests that only require your accountid (such as requests to get the viewer page) can be non-secure.

Responses

The response to a request will include a HTTP status code. The status codes have the following meaning:

  • 200 - The request was successful.
  • 400s - The request was malformed. The JSON response will contain an errorMessage that provides more information about the error.
  • 500s - There was a server error. Depending on the type of error, you can either try your request again later or contact us for assistance.

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

POST https://api.screenleap.com/v2/screen-shares/{screenShareCode}/stop

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

GET https://api.screenleap.com/v2/screen-shares/{screenShareCode}

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

GET https://api.screenleap.com/v2/screen-shares

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

GET https://api.screenleap.com/v2/recent-screen-shares

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).


Continue to JavaScript Calls »
/api/doc/http-calls
OK
OK
OK
...