OpenTok REST API reference

Use the OpenTok REST API to generate OpenTok sessions and to work with OpenTok archives. The REST API includes the following methods:

The OpenTok REST API is used by developers to generate sessions. The OpenTok SDKs wrap the OpenTok REST API to make it easier to make calls to the OpenTok platform.

Authentication

REST API calls must be authenticated using a custom HTTP header: X-TB-PARTNER-AUTH. Send your API key and partner secret concatenated with a colon:

X-TB-PARTNER-AUTH: <api_key>:<partner_secret>

To call the function from the command line, you could issue a command like the following:

export TB_url=https://api.opentok.com/hl/session/create
headerstr="X-TB-PARTNER-AUTH: API_KEY:API_SECRET"
curl -X POST -H "$headerstr" $TB_url

Replace the API_KEY and API_SECRET with the API key and partner secret provided to you in your OpenTok dashboard.

Creating a session

Generate a new session.

Resource URL:

https://api.opentok.com/hl/session/create

Resource verb:

POST

POST Parameters

location

The location setting is optional, and generally you should not include it. This setting is an IP address that TokBox will use to situate the session in its global network. If no location hint is passed in (which is recommended), the session uses a media server based on the location of the first client connecting to the session. Pass a location hint in only if you know the general geographic region (and a representative IP address) and you think the first client connecting may not be in that region. If you need to specify an IP address, replace IP_ADDRESS with an IP address that is representative of the geographical location for the session.

p2p.preference

Set to "enabled" if you prefer clients to attempt to send audio-video streams directly to other clients; set to "disabled" for sessions that use the OpenTok Media Router. (Optional; the default setting is disabled -- the session uses the OpenTok Media Router.)

The OpenTok Media Router provides the following benefits:

  • The OpenTok Media Router can decrease bandwidth usage in multiparty sessions. (When the p2p.preference property is set to "enabled", each client must send a separate audio-video stream to each client subscribing to it.)
  • The OpenTok Media Router can improve the quality of the user experience through Intelligent Quality Control. With Intelligent Quality Control, if a client's connectivity degrades to a degree that it does not support video for a stream it's subscribing to, the video is dropped on that client (without affecting other clients), and the client receives audio only. If the client's connectivity improves, the video returns.
  • The OpenTok Media Router supports the archiving and playback feature, which lets you record, save, and retrieve OpenTok sessions.

With the p2p.preference property set to "enabled", the session will attempt to transmit streams directly between clients. If clients cannot connect due to firewall restrictions, the session uses the OpenTok TURN server to relay audio-video streams.

Sample Request

POST /session/create HTTP/1.1
Host: https://api.opentok.com/hl
X-TB-PARTNER-AUTH: api_key:partner_secret

location=10.1.200.30&p2p.preference=disabled

The following command line example creates a session that uses the OpenTok Media Router and specifies a location hint:

export api_key=12345 # replace with your API key
export api_secret=123456123456123456 # replace with your API secret
export TB_url=https://api.opentok.com/hl/session/create
headerstr="X-TB-PARTNER-AUTH:$api_key:$api_secret"
datastr=location:10.1.200.30 \
curl \
   -X POST \
   -H "$headerstr" \
   -H "$datastr" \
   $TB_url

The following command line example creates a session that attempts to transmit streams directly between clients (without using the OpenTok Media Router):

export api_key=12345 # replace with your API key
export api_secret=123456123456123456 # replace with your API secret
export TB_url=https://api.opentok.com/hl/session/create
headerstr="X-TB-PARTNER-AUTH:$api_key:$api_secret"
datastr=p2p.preference:enabled \
curl \
   -X POST \
   -H "$headerstr" \
   -H "$datastr" \
   $TB_url

Sample Response

The response is XML data of the following form:

<sessions>
  <Session>
    <session_id>SESSION_ID</session_id>
    <partner_id>API_KEY</partner_id>
    <create_dt>DATE</create_dt>
    <session_status></session_status>
  </Session>
</sessions>

Starting an archive recording

To start recording an archive of an OpenTok 2.0 session, submit an HTTP POST request.

Clients must be actively connected to the OpenTok session for you to successfully start recording an archive

You can only record one archive at a time for a given session. You can only record archives of sessions that use the OpenTok Media Router (with the media mode set to routed); you cannot archive sessions that have the media mode set to relayed. (See The OpenTok Media Router and media modes.)

HTTP POST to archive

Submit an HTTP POST request to the following URL:

    https://api.opentok.com/v2/partner/<api_key>/archive

Replace <api_key> with your OpenTok API key. See the OpenTok dashboard.

POST header properties

API calls must be authenticated using a custom HTTP header: X-TB-PARTNER-AUTH. Send your API key and API secret concatenated with a colon:

    X-TB-PARTNER-AUTH: <api_key>:<api_secret>

(See the OpenTok dashboard.)

Set the Content-type header to application/json:

Content-Type:application/json

POST data

Include a JSON object of the following form as the POST data:

{
    "sessionId" : "session_id",
    "name" : "archive_name"
}

The JSON object includes the following properties:

  • sessionId — The session ID of the OpenTok session you want to start archiving
  • name — (Optional) The name of the archive (for your own identification)

Response

The raw data of the HTTP response, with status code 200, is a JSON-encoded message of the following form:

{
  "createdAt" : 1384221730555,
  "duration" : 0,
  "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
  "name" : "The archive name you supplied",
  "partnerId" : 234567,
  "reason" : "",
  "sessionId" : "flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN",
  "size" : 0,
  "status" : "started",
  "url" : null
}

The JSON object includes the following properties:

  • createdAt — The timestamp for when the archive started recording, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
  • partnerId — Your OpenTok API key.
  • sessionId — The session ID of the OpenTok session being archived.
  • id — The unique archive ID. Store this value for later use (for example, to stop the recording).
  • name — The name of the archive you supplied (this is optional)

The HTTP response has a 400 status code in the following cases:

  • You do not pass in a session ID or you pass in an invalid session ID.
  • No clients are actively connected to the OpenTok session.

The HTTP response has a 403 status code if you pass in an invalid OpenTok API key or partner secret.

The HTTP response has a 404 status code if the session does not exist.

The HTTP response has a 409 status code if you attempt to start an archive for a session that does not use the OpenTok Media Router or if the session is already being recorded.

The HTTP response has a 500 status code for an OpenTok server error.

Example

The following command line example starts recording an archive for an OpenTok session:

api_key=12345
api_secret=234567890
session_id=2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4
name="Foo"
data='{"sessionId" : "'$session_id'", "name" : "'$name'"}'
curl \
     -i \
     -H "Content-Type: application/json" \
     -X POST -H "X-TB-PARTNER-AUTH:$api_key:$api_secret" -d "$data" \
     https://api.opentok.com/v2/partner/$api_key/archive
  • Set the values for api_key and api_secret to your OpenTok API key and partner secret.
  • Set the session_id value to the session ID of the OpenTok 2.0 session you want to archive.
  • Set the name value to the archive name (this is optional).

Stopping an archive recording

To stop recording an archive, submit an HTTP POST request.

Archives automatically stop recording after 90 minutes or when all clients have disconnected from the session being archived.

HTTP POST to archive

Submit an HTTP POST request to the following URL:

https://api.opentok.com/v2/partner/<api_key>/archive/<archive_id>/stop

Replace <api_key> with your OpenTok API key. See https://dashboard.tokbox.com.

Replace <archive_id> with the archive ID. You can obtain the archive ID from the response to the API call to start recording the archive.

POST header properties

API calls must be authenticated using a custom HTTP header: X-TB-PARTNER-AUTH. Send your API key and API secret concatenated with a colon:

X-TB-PARTNER-AUTH: <api_key>:<api_secret>

(See https://dashboard.tokbox.com.)

Response

The raw data of the HTTP response, with status code 200, is a JSON-encoded message of the following form:

{
  "createdAt" : 1384221730555,
  "duration" : 60,
  "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
  "name" : "The archive name you supplied",
  "partnerId" : 234567,
  "reason" : "",
  "sessionId" : "flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN",
  "size" : 0,
  "status" : "stopped",
  "url" : null
}

The JSON object includes the following properties:

  • createdAt — The timestamp for when the archive started recording, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
  • partnerId — Your OpenTok API key.
  • sessionId — The session ID of the OpenTok session that was archived.
  • id — The unique archive ID.
  • name — The name of the archive you supplied (this is optional)

The HTTP response has a 400 status code if you do not pass in a session ID or you pass in an invalid session ID.

The HTTP response has a 403 status code if you pass in an invalid OpenTok API key or partner secret.

The HTTP response has a 404 status code if you pass in an invalid archive ID.

The HTTP response has a 409 status code if you attempt to stop an archive that is not being recorded.

The HTTP response has a 500 status code for an OpenTok server error.

Example

The following command line example stops recording an archive for an OpenTok session:

api_key=123456
api_secret=2345678
id=b40ef09b-3811-4726-b508-e41a0f96c68f
curl \
     -i \
     -X POST -H "X-TB-PARTNER-AUTH:$api_key:$api_secret" \
     https://api.opentok.com/v2/partner/$api_key/archive/$id/stop
  • Set the values for api_key and api_secret to your OpenTok API key and partner secret.
  • Set the id value to the archive ID. You can obtain the archive ID from the response to the API call to start recording the archive.

Listing archives

To list archives for your API key, both completed and in-progress, submit an HTTP GET request.

HTTP GET to archive

Submit an HTTP GET request to the following URL:

https://api.opentok.com/v2/partner/<api_key>/archive?offset=<offset>&count=<count>

Replace <api_key> with your OpenTok API key. See https://dashboard.tokbox.com.

Replace <offset> with the index offset of the first archive. 0 is offset of the most recently started archive (excluding deleted archive). 1 is the offset of the archive that started prior to the most recent archive. Setting <offset> is optional; the default is 0.

Replace <count> with the number of archives to be returned. Setting <count> is optional. The default number of archives returned is 50 (or fewer, if there are fewer than 50 archives). The maximum number of archives the call will return is 1000.

Deleted archives are not included in the results of this API call.

Replace <api_key> with your OpenTok API key. See https://dashboard.tokbox.com.

GET header properties

API calls must be authenticated using a custom HTTP header: X-TB-PARTNER-AUTH. Send your API key and API secret concatenated with a colon:

X-TB-PARTNER-AUTH: <api_key>:<api_secret>

(See https://dashboard.tokbox.com.)

Response

The raw data of the HTTP response, with status code 200, is a JSON-encoded message of the following form:

{
  "count" : 2,
  "items" : [ {
    "createdAt" : 1384221730000,
    "duration" : 5049,
    "id" : "09141e29-8770-439b-b180-337d7e637545",
    "name" : "Foo",
    "partnerId" : 123456,
    "reason" : "",
    "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
    "size" : 247748791,
    "status" : "available",
    "url" : "http://tokbox.com.archive2.s3.amazonaws.com/123456/09141e29-8770-439b-b180-337d7e637545/archive.mp4"
  }, {
    "createdAt" : 1384221380000,
    "duration" : 328,
    "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
    "name" : "Foo",
    "partnerId" : 123456,
    "reason" : "",
    "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
    "size" : 18023312,
    "status" : "available",
    "url" : "http://tokbox.com.archive2.s3.amazonaws.com/123456/b40ef09b-3811-4726-b508-e41a0f96c68f/archive.mp4"
  } ]

The JSON object includes the following properties:

  • count — The total number of archives for the API key.
  • items — An array of objects defining each archive retrieved. Archives are listed from the newest to the oldest in the return set.

Each archive object (item) has the following properties:

  • createdAt — The timestamp for when the archive started recording, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
  • duration — The duration of the archive in seconds. For archives that have are being recorded (with the status property set to "started"), this value is set to 0.
  • id — The unique archive ID.
  • name — The name of the archive you supplied (this is optional)
  • partnerId — Your OpenTok API key.
  • reason — For archives with the status "stopped", this can be set to "90 mins exceeded", "failure", "session ended", "user initiated". For archives with the status "failed", this can be set to "system failure".
  • sessionId — The session ID of the OpenTok session that was archived.
  • status — The status of the archive:
    • "available" — The archive is available for download from the OpenTok cloud.
    • "expired" — The archive is no longer available for download from the OpenTok cloud.
    • "failed" — The archive recording failed.
    • "started" — The archive started and is in the process of being recorded.
    • "stopped" — The archive stopped recording.
    • "uploaded" — The archive is available for download from the S3 bucket you specified in the OpenTok dashboard.
  • size — The size of the MP4 file. For archives that have not been generated, this value is set to 0.
  • url — The download URL of the available MP4 file. This is only set for an archive with the status set to "available"; for other archives, (including archives with the status "uploaded") this property is set to null. The download URL is obfuscated, and the file is only available from the URL for 10 minutes. To generate a new URL, use the REST API for retrieving archive information or listing archives.

The HTTP response has a 403 status code if you pass in an invalid OpenTok API key or partner secret.

The HTTP response has a 500 status code for an OpenTok server error.

Example

The following command line example retrieves information for all archives:

api_key=12345
api_secret=234567890
curl \
    -i \
    -X GET \
    -H "X-TB-PARTNER-AUTH:$api_key:$api_secret" \
    https://api.opentok.com/v2/partner/$api_key/archive

Set the values for api_key and api_secret to your OpenTok API key and partner secret.

Retrieving archive information

To retrieve information about a specific archive, submit an HTTP GET request.

You can also retrieve information about multiple archives. See Listing archives.

HTTP GET to archive

Submit an HTTP GET request to the following URL:

https://api.opentok.com/v2/partner/<api_key>/archive/<archive_id>

GET header properties

API calls must be authenticated using a custom HTTP header: X-TB-PARTNER-AUTH. Send your API key and API secret concatenated with a colon:

X-TB-PARTNER-AUTH: <api_key>:<api_secret>

(See https://dashboard.tokbox.com.)

Response

The raw data of the HTTP response, with status code 200, is a JSON-encoded message of the following form:

{
 "createdAt" : 1384221730000,
    "duration" : 5049,
    "id" : "09141e29-8770-439b-b180-337d7e637545",
    "name" : "Foo",
    "partnerId" : 123456,
    "reason" : "",
    "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
    "size" : 247748791,
    "status" : "available",
    "url" : "http://tokbox.com.archive2.s3.amazonaws.com/123456/09141e29-8770-439b-b180-337d7e637545/archive.mp4"
}

The JSON object includes the following properties:

  • createdAt — The timestamp for when the archive started recording, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
  • duration — The duration of the archive in seconds. For archives that have are being recorded (with the status property set to "started"), this value is set to 0.
  • id — The unique archive ID.
  • name — The name of the archive you supplied (this is optional)
  • partnerId — Your OpenTok API key.
  • reason — For archives with the status "stopped", this can be set to "90 mins exceeded", "failure", "session ended", "user initiated". For archives with the status "failed", this can be set to "system failure".
  • sessionId — The session ID of the OpenTok session that was archived.
  • status — The status of the archive:
    • "available" — The archive is available for download from the OpenTok cloud.
    • "deleted" — The archive was deleted.
    • "expired" — The archive is no longer available for download from the OpenTok cloud.
    • "failed" — The archive recording failed.
    • "started" — The archive started and is in the process of being recorded.
    • "stopped" — The archive stopped recording.
    • "uploaded" — The archive is available for download from the S3 bucket you specified in the OpenTok dashboard.
  • size — The size of the MP4 file. For archives that have not been generated, this value is set to 0.
  • url — The download URL of the available MP4 file. This is only set for an archive with the status set to "available"; for other archives, (including archives with the status "uploaded") this property is set to null. The download URL is obfuscated, and the file is only available from the URL for 10 minutes. To generate a new URL, use the REST API for retrieving archive information or listing archives.

The HTTP response has a 400 status code if you do not pass in a session ID or you pass in an invalid archive ID.

The HTTP response has a 403 status code if you pass in an invalid OpenTok API key or partner secret.

The HTTP response has a 500 status code for an OpenTok server error.

Example

The following command line example retrieves information for an archive:

api_key=12345
api_secret=234567890
id=23435236235235235235
curl \
    -i \
    -X GET \
    -H "X-TB-PARTNER-AUTH:$api_key:$api_secret" \
    https://api.opentok.com/v2/partner/$api_key/archive/$archive
  • Set the values for api_key and api_secret to your OpenTok API key and partner secret.
  • Set the id value to the archive ID.

Deleting an archive

To delete an archive, submit an HTTP DELETE request.

You can only delete an archive which has a status of "available" or "uploaded". Deleting an archive removes its record from the list of archives (see Listing archives). For an "available" archive, it also removes the archive file, making it unavailable for download.

HTTP DELETE to archive

Submit an HTTP DELETE request to the following URL:

https://api.opentok.com/v2/partner/<api_key>/archive/<archive_id>

Replace <api_key> with your OpenTok API key. See https://dashboard.tokbox.com.

Replace <archive_id> with the archive ID.

DELETE header properties

API calls must be authenticated using a custom HTTP header: X-TB-PARTNER-AUTH. Send your API key and API secret concatenated with a colon:

X-TB-PARTNER-AUTH: <api_key>:<api_secret>

(See https://dashboard.tokbox.com.)

Response

An HTTP response with a status code of 204 indicates that the archive has been deleted.

The HTTP response has a 403 status code if you pass in an invalid OpenTok API key, invalid partner secret, or invalid archive ID.

The HTTP response has a 409 status code if the status of the archive is not "uploaded", "available", or "deleted".

The HTTP response has a 500 status code for an OpenTok server error.

Example

The following command line example deletes an archive:

api_key=12345
api_secret=234567890
id=b40ef09b-3811-4726-b508-e41a0f96c68f
curl \
     -i \
     -X DELETE \
     -H "X-TB-PARTNER-AUTH:$api_key:$api_secret" \
     https://api.opentok.com/v2/partner/$api_key/archive/$id
  • Set the values for api_key and api_secret to your OpenTok API key and partner secret.
  • Set the id value to the ID of the archive to delete.

IRC Live Chat

Have a quick question? Chat with TokBox Support on IRC. Join chat