Find running rooms

Optional parameters: skip (number): number of rooms to skip. limit (number): maximum number of rooms to return.

POST /api/v3/runningrooms HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "skip": 5
   "limit": 5
}

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "rooms": [
      {
         "room": "123456789",
         "starttime": "2016-12-19T14:20:22Z",
         "publicinvitation": "https://realtime.samesurf.com/{room}/{leadertoken}",
         "privateinvitation": "https://realtime.samesurf.com/{room}/{token}",
         "title": "Room Title"
      },
      ...
   ],
   "totalrooms": 15,
   "success": true,
}

Create a room

Optional parameters: starturl (string) - url of the initial webpage to be shown. title (string) - a description of the room, this will show in analytics. bookmarks (array) - overrides the default bookmarks displayed in the room. (each bookmark must contain: name (string) - description of the bookmark, link (string) - url to the webpage). session (object) - adds session data to the created room. session.cookies (array) - cookies to add to the room (each cookie must contain: domain (string), path (string), name (string), value (string), secure (bool), httponly (bool)) session.storage (array) - storage key/value pairs to add to the room (each storage must contain: domain (string), name (string), value (string)) disabledfeatures (array) - features to disable in the room, the options include: MODE_DOCUMENT_SHARE MODE_VIDEO_SHARE MODE_SCREEN_SHARE MODE_LOGOUT TOOLS_SCREEN_RECORDING TOOLS_VIDEO_CHAT TOOLS_AUDIO_CHAT TOOLS_12MANY_VIDEO TOOLS_MOUSE_TRACKING TOOLS_DISCONNECT_USER

POST /api/v3/create HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "starturl":"http://www.samesurf.com",
   "title": "Product demo",
   "bookmarks": [
      {
         "name": "Samesurrf",
         "link": "https://www.samesurf.com"
      }
   ],
   "session": {
      "cookies": [
         {
            "domain": "twitter.com",
            "path": "/",
            "name": "auth_token",
            "value": "your_auth_token",
            "secure": true,
            "httponly": true
         }
      ],
      "storage": [
         {
            "domain": "mydomain.com",
            "name": "test",
            "value": "test_value"
         }
      ]
   }
}

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "room":"123456789",
   "token":"ABCDEF123456",
   "leadertoken":"ABCDEF123456",
   "privateinvitation":"https://realtime.samesurf.com/{room}/{leadertoken}",
   "publicinvitation":"https://realtime.samesurf.com/{room}/{token}",
   "success":true
}

This is an example using jQuery for ajax, and jsrsasign to create the JWT token.

var token_body = {
  iat: Math.floor(new Date().getTime() / 1000),
  sub: "YOUR API KEY",
};

var token = KJUR.jws.JWS.sign("HS256", { typ: "JWT" }, token_body, "YOUR API SECRET");
var data = {
  starturl: "http://www.yahoo.com"
};

$.ajax({
   url: "https://api.samesurf.com/api/v3/create",
   dataType: "json",
   type: "POST",
   data: JSON.stringify(data),
   beforeSend: function (xhr) {
      xhr.setRequestHeader("Content-Type", "application/json");
      xhr.setRequestHeader("Authorization", "Bearer " + token);
   },
   error: function () {
      // error handler
   },
   success: function (data) {
      return data;
   }
});

The last example used the HS256 signing algorithm and embeds the secret in a page. If you don't wish to do this, you could call the api from you own server, or enable the "none" algorithm for the api key. Here is an example doing just that:

var token_body = {
   iat: Math.floor(new Date().getTime() / 1000),
   sub: "YOUR API KEY",
};
var token = KJUR.jws.JWS.sign("none", { typ: "JWT" }, token_body);
var data = {
   starturl: "http://www.yahoo.com"
};
$.ajax({
   url: "https://api.samesurf.com/api/v3/create",
   dataType: "json",
   type: "POST",
   data: JSON.stringify(data),
   beforeSend: function (xhr) {
      xhr.setRequestHeader("Content-Type", "application/json");
      xhr.setRequestHeader("Authorization", "Bearer " + token);
   },
   error: function () {
      // error handler
   },
   success: function (data) {
      console.log("this is a link to the room", data.publicinvitation);
      return data;
   }
});

Scheduling a room

As well as creating a room to be used straight away, as in the previous examples, you can also schedule a room to be used at a specified date.

Pass through an eventtime for the room to be scheduled, you can also specify the timezone with the eventtime if it's not UTC time.

Required parameters: eventtime (string) - date in format dd/MM/yyyyThh:mm:ssZ, you only need the Z if the time is UTC.

Optional parameters: timezone (string) - you only need to add a timezone if the event time is not in UTC, example "Europe/London". lengthinminutes (number) - duration of scheduled event. invitees (string) - comma seperated list of invitee email address, these will be emailed an invitation. invitemessage (string) - extra text to add to the invitation email.

POST /api/v3/create HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "starturl":"http://www.samesurf.com",
   "title": "Product Demo",
   "eventtime": "2017-02-22T16:30:00",
   "timezone": "Europe/London"
}

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "room":"123456789",
   "token":"ABCDEF123456",
   "leadertoken":"ABCDEF123456",
   "privateinvitation":"https://realtime.samesurf.com/{room}/{leadertoken}",
   "publicinvitation":"https://realtime.samesurf.com/{room}/{token}",
   "success":true
}

Finding invitation link for a room

Required parameters: room (string) - room number.

POST /api/v3/find HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "room":"123456789"
}

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "room":"123456789",
   "token":"ABCDEF123456",
   "leadertoken":"ABCDEF123456",
   "publicinvitation":"https://realtime.samesurf.com/{room}/{token}",
   "success":true
}

Create limited use invitation

Required parameters: room (string) - room number. usagelimit (int) - number of times the invitation can be used isleader (bool) - whether the user should become the leader if they are the first user to enter the room.

Optional parameters: usersname (string) - automatically set the user's name when they enter the room.

POST /api/v3/createlimitedusetoken HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "room":"123456789",
   "usagelimit": 1,
   "isleader": true
}

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "token":"ABCDEF123456",
   "link":"https://realtime.samesurf.com/{room}/{token}",
   "success":true
}

Delete limited use invitation

Required parameters: token (string) - token for invitation.

POST /api/v3/deletelimitedusetoken HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "token":"ABCDEF123456"
}

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "success":true
}

Create video public link

This will create a temporary public link to a screen recording.

Required parameters: room (string) - room number.

POST /api/v3/screenrecordingpubliclink HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "room":"123456789",
   "recording": 2,
   "validfor": 30
}

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "link":"temp_url_to_video",
   "success":true
}

Create thumbnail public link

This will create a temporary public link to a screen recording's thumbnail.

Required parameters: room (string) - room number.

POST /api/v3/screenrecordingthumbnail HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "room":"123456789",
   "recording": 3,
   "validfor": 10
}

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "link":"temp_url_to_thumbnail",
   "success":true
}

Create screenshot public link

This will create a temporary public link to a screen recording's full size (or custom size) screenshot.

Required parameters: room (string) - room number.

Optional parameters: recording (number) - specify the number of the recording if there are multiple, default is 0. validfor (number) - how long the link should be valid for in minutes, default is 60. width (number) - width of the returned screenshot. height (number) - height of the returned screenshot.

If only the width is specified, height will automatically be scaled to match.

POST /api/v3/screenrecordingimage HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "room":"123456789",
   "recording": 2,
   "validfor": 30,
   "width": 400
}

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "link":"temp_url_to_screenshot",
   "success":true
}

Accessing analytics overview

There are no required parameters for this call.

POST /api/v3/analyticsoverview HTTP/1.1
Host: api.samesurf.com
Content-Length: 0
Authorization: Bearer YOUR-BEARER-TOKEN

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "url_latest": "http://www.google.com",
   "url_most_popular": "google.com",
   "rooms_total": 131,
   "rooms_today": 20,
   "rooms_thisweek": 43,
   "rooms_thismonth": 102,
   "averageduration_alltime": 34,
   "averageduration_today": 28,
   "averageduration_thisweek":33,
   "averageduration_thismonth": 33,
   "success": true
}

Accessing list of rooms

Optional parameters: skip (number): number of rooms to skip. limit (number): maximum number of rooms to return.

POST /api/v3/analyticsrooms HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "skip":20,
   "take": 20
}

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "total_rooms": "123",
   "rooms": [
      {
         "room": "123456789",
         "title": "Product Demo",
         "date": "2017-01-13T10:10:16Z",
         "duration": 1234,
         "screenrecordings": 1
      },
      {
         "room": "234567890",
         "title": "Testing",
         "date": "2016-12-22T16:22:01Z",
         "duration": 2687,
         "screenrecordings": 2
      }.
      ...
   },
   "success": true
}

Accessing room analytics

Required parameters: room (string) - room number

Optional parameters version (int) - the room version if the same room number has been used multiple times, default is 0.

POST /api/v3/roomanalytics HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "room":"123456789",
   "version": 1
}

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "title": null,
   "events": [
      {
         "type": "start",
         "date": "2017-01-13T10:10:26Z",
         "sender": "",
         "target": "",
         "data": "564906354"
      },
      {
         "type": "url",
         "date": "2017-01-13T10:10:26Z",
         "sender": "",
         "target": "",
         "data": "http://www.google.com"
      },
      ...
   ],
   "users": [
      {
         "guid": "F65CFEB90EF3D44DC759AC129BFE1F5BF2A29986",
         "host": true,
         "joinedat": "2017-01-13T10:10:26Z",
         "leftat": "2017-01-13T10:11:06Z",
         "name": "Host",
         "ipaddress": "1.2.3.4",
         "city": "London",
         "country": "United Kingdom"
      },
      ...
   ],
   "success": true
}

Create subscription

This call can only be made from a reseller subscription.

Required parameters: name (string) - name of subscription to be created, must be unique licensecount (number) - number of licenses for subscription

Optional parameters: configuration_overrides (array) - override settings that control how the subscription and their rooms function (each override must contain: key (string) - name of override, value (string) - value of override). Valid keys: communications_active default_logout_url demotimer_active demotimer_logout_url disable_urlbar_all disable_urlbar_follower hide_bookmark_add hide_bookmark_header hide_bookmarks hide_modes_menu inroomchat_active invitations_active passcontrol_active preload_host_invitations social_changename_active suppress_beforeunload welcome_active bookmarks (array) - overrides the default bookmarks (each bookmark must contain: name (string) - description of the bookmark, link (string) - url to the webpage). disabledfeatures (array) - features to disable in the subscription, the options include: MODE_DOCUMENT_SHARE MODE_VIDEO_SHARE MODE_SCREEN_SHARE MODE_LOGOUT TOOLS_SCREEN_RECORDING TOOLS_VIDEO_CHAT TOOLS_AUDIO_CHAT TOOLS_12MANY_VIDEO TOOLS_MOUSE_TRACKING TOOLS_DISCONNECT_USER

POST /api/v3/reseller/createsubscription HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "name":"ResoldSubscriptionName",
   "licensecount": 10,
   "configuration_overrides": [
      {
         "key":"communications_active", 
         "value":"false"
      },
      {
         "key":"default_logout_url",
         "value":"http://www.mywebsite.com"
      }
   ],
   "bookmarks": [
      {
         "name": "Samesurrf",
         "link": "https://www.samesurf.com"
      }
   ],
   "disabled_features": [
      "MODE_SCREEN_SHARE",
      "MODE_VIDEO_SHARE"
   ]
}

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "success":true
}

Delete subscription

This call can only be made from a reseller subscription.

Required parameters: name (string) - name of the subscription to be deleted

POST /api/v3/reseller/deletesubscription HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "name":"ResoldSubscription1"
}

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "success":true
}

Create api key

This call can only be made from a reseller subscription.

Required parameters: subscription (string) - name of subscription

POST /api/v3/reseller/createapikey HTTP/1.1
Host: api.samesurf.com
Authorization: Bearer YOUR-BEARER-TOKEN
Content-Type: application/json
{
   "subscription":"ResoldSubscriptionName"
}

Example Response:

HTTP/1.1 200 OK
Date: Sat, 18 Jan 2025 22:40:45 GMT
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
   "success":true,
   "apikey": "generated_api_key",
   "apisecret": "generated_api_secret"
}