HTTP Reference

StreamAPI's HTTP API is a REST-like protocol. Requests are always either GET or POST methods as specified per API function. Replies are always formatted using XML. API requests originate at your server, not from the end user's web browser. We offer sample code and official client libraries for only some languages, although using our interface is trivial in virtually any language.

All API requests must include a minimum of three parameters: key (API key), sig (signature), and rid (request ID). The API key identifies your account, the signature lets us verify that the request is legitimate and has not been tampered with, and the rid prevents the replaying of previous requests. The rid is a number that you generate and must increase with every request.

• API and Secret Keys
• Signing Your Requests
• Generating the Request ID
• Create Session
• Get Live Session Info
• List Live Sessions
• Get public host ID
• Get private host ID
• List Video Recordings

1) API Key and Secret key

When you sign up for a StreamAPI account you are assigned a Secret Key and an API Key. You can see these in your API Settings page from within your account. These are to be kept private and should never be shared.

API Settings

Signing Your Requests

A new signature must be generated for every API request. The signature is an MD5 hash of the current request values, request_id, and your secret key. Generated as follows, in pseduo code: md5_hex(concatenate(request_param_values_in_alphabetical_order_of_param_names,secret_key,rid))

A typical example of a create session (with optional parameters username and site_user_id) request is shown here:

Parameters
key=ZS1N632EVFW87NWSHJ7I263FDDD2F3AY site_user_id=123456 username=John+Smith secret_key=9JDIEJDYQPIKREWCDUTQEOPJVSDEWQSE rid=1240267305342 sig = MD5(key + site_user_id + username + secret_key + rid) = MD5(ZS1N632EVFW87NWSHJ7I263FDDD2F3AY123456John+Smith9JDIEJDYQPIKREWCDUTQEOPJVSDEWQSE1240267305342)
Request
POST /service/session/create HTTP/1.1 TE: deflate,gzip;q=0.3 Connection: TE, close Host: localhost User-Agent: WWW::StreamAPI/0.01 Content-Length: 131 Content-Type: application/x-www-form-urlencoded sig=cadabd71a4c9b10c2acba49ca7e03751&site_user_id=123456&rid=1240267305342&key=ZS1N632EVFW87NWSHJ7I263FDDD2F3AY&username=John+Smith
Response
<stickam_api> <private_hostid>ZSO0QCRGQTSTWFWXNVYTDUU2DU8PQMMM</private_hostid> <public_hostid>1000000780</public_hostid> <code>0</code> </stickam_api>

2) Generating the Request ID

The request ID (rid) parameter must increase with every request. The easiest way to generate it is by using the current system time in milliseconds.

Example code in Java, Python, and Perl

/* Java */ long requestId = System.currentTimeMillis(); # Python import time request_id = int(time.time() * 1000) # Perl use Time::Hires qw( gettimeofday ); my $request_id = int(gettimeofday * 1000);

Status Codes

All API responses include status code (<code></code>). Anything other than 0 (zero) is an error. When a request is not successful a human readable message will be available, such as <msg>Invalid API key</msg>.

3) Create Session

Description

Creates a new StreamAPI session which includes a private_hostid (for broadcasters) and public_hostid (for viewers).

URL

http://api.streamapi.com/service/session/create

Method

POST

Parameters

Required

• key
• sig
• rid

Optional

• site_user_id [0-9]
Overrides auto-generated public_hostid with your site's user ID
• username [a-zA-Z0-9]
Displayed in UserList component and as overlay in video components.
• fme_key [a-zA-Z0-9]
To create a live session using a different flash media encoder (such as the Adobe Flash Media Live Encoder), you can pass in a fme_key value, which is a secret unique value that you can set for that user. The fme_key value that is set in StreamAPI and that your user will need to enter in the URL will need to be rtmp://fme.streamapi.com/hd_receiver/[public_host_id]-[fme_key_value] For example, if the fme_key value for a user is f1b8221d2b69 and the user's public host id is 1000016132, the real fme_key that StreamAPI will set is 1000016132-f1b8221d2b69 and the RTMP URL will be rtmp://fme.streamapi.com/hd_receiver/1000016132-f1b8221d2b69
• is_video_private
To create a live session that will allow only authenticated viewers to see the live video and join the live sesion, you can pass in is_video_private with a value of true

Status Codes

Code	Description
1	Missing required parameter(s)
8	No user found
46	No session found
100	Unknown Error
200	Invalid API key
201	Cannot request this call for user that was not created by API caller
202	Invalid sig (or signature) value
203	Invalid request ID value

4) Get Live Session Info

Description

Fetch information about a particular session using its public_hostid.

URL

http://api.streamapi.com/service/session/live

Method

GET

Parameters

Required

• key
• sig
• rid
• public_hostid [0-9]

Optional

NONE

Example response

<?xml version="1.0" encoding="UTF-8" ?> <streamapi> <is_live>true</is_live> <private_hostid>123456</private_hostid> <username>liveuser</username> <start_time>758955621</start_time> <duration>302</duration> <channel_id>123456</channel_id> <code>0</code> </streamapi>

Status Codes

Code	Description
1	Missing required parameter(s)
8	No user found
100	Unknown Error
200	Invalid API key
202	Invalid sig (or signature) value
203	Invalid request ID value

5) List Live Sessions

Description

Fetch a list of all sessions that are currently streaming. Note: There is up to a 60 second delay from the time a session begins streaming to the time it will show up in this list.

URL

http://api.streamapi.com/service/session/live/list

Method

GET

Parameters

Required

• key
• sig
• rid

Optional

NONE

Example response

<?xml version="1.0" encoding="UTF-8" ?> <streamapi> <live_sessions> <session> <public_hostid>1234567</public_hostid> <public_hostid>IKLJYKD83KDI3KRJCMSKWI3L4LSI3L32</public_hostid> </session> <session> <public_hostid>98765433</public_hostid> <public_hostid>DI38DK38DLSDFJSD192U707SDFJ38D88</public_hostid> </session> </live_sessions> <code>0</code> </streamapi>

Status Codes

Code	Description
1	Missing required parameter(s)
100	Unknown Error
200	Invalid API key
202	Invalid sig (or signature) value
203	Invalid request ID value

6) Get public host ID

Description

A helper function that tells you what the public host ID is for a particular private host ID.

URL

http://api.streamapi.com/service/host/id/public

Method

GET

Parameters

Required

• key
• sig
• rid
• private_hostid [A-Z0-9]

Optional

NONE

Example response

<?xml version="1.0" encoding="UTF-8" ?> <streamapi> <private_hostid>AIKE837DY4FKMC762OKCUWDCF4KMMOWH</private_hostid> <public_hostid>123456</public_hostid> <code>0</code> </streamapi>

Status Codes

Code	Description
1	Missing required parameter(s)
8	No user found
46	No session found
100	Unknown Error
200	Invalid API key
201	Cannot request this call for user that was not created by API caller
202	Invalid sig (or signature) value
203	Invalid request ID value

7) Get private host ID

Description

A helper function that tells you what the private host ID is for a particular public host ID.

URL

http://api.streamapi.com/service/host/id/private

Method

GET

Parameters

Required

• key
• sig
• rid
• public_hostid [0-9]

Optional

NONE

Example response

<?xml version="1.0" encoding="UTF-8" ?> <streamapi> <private_hostid>AIKE837DY4FKMC762OKCUWDCF4KMMOWH</private_hostid> <public_hostid>123456</public_hostid> <code>0</code> </streamapi>

Status Codes

Code	Description
1	Missing required parameter(s)
8	No user found
46	No session found
100	Unknown Error
200	Invalid API key
201	Cannot request this call for user that was not created by API caller
202	Invalid sig (or signature) value
203	Invalid request ID value

8) Get live video recordings

Description

List live session recordings for a site, host, or date range

URL

http://api.streamapi.com/service/video/list

Method

GET

Parameters

Required

• key
• sig
• rid

Optional

• public_hostid [0-9]
• start_date [0-9] - milliseconds
Start creation date (in milliseconds) of videos to be retrieved.
• end_date [0-9] - milliseconds
Latest creation date (in milliseconds) of videos to be retrieved.

Example response

<?xml version="1.0" encoding="UTF-8" ?> - <streamapi> - <videos> - <video id="58"> <public_hostid>1000000760</public_hostid> <duration>134.301</duration> <channel_id>1241821235936</channel_id> <creation_date>1241821382237</creation_date> <filename>28c5d38b3ca8722fd8c351eaca406a6ce7e8bd54_1241821235063.flv</filename> <size>568564</size> <url>http://static.streamapi.com/video/100/000/076/0/28c5d38b3ca8722fd8c351eaca406a6ce7e8bd54_1241821235063.flv</url> <embed_code><![CDATA[<embed height="240" width="320" flashVars="&file=http://static.streamapi.com/video/100/000/076/0/28c5d38b3ca8722fd8c351eaca406a6ce7e8bd54_1241821235063.flv&image=http://static.streamapi.com/video/100/000/076/0/28c5d38b3ca8722fd8c351eaca406a6ce7e8bd54_1241821235063.flv.jpg&bufferlength=5&volume=10&autostart=false&icons=false&controlbar=bottom&fullscreen=true&dock=false" allowfullscreen="true" allowscriptaccess="always" quality="high" name="mpl" id="mpl" style="" src="https://streamapi.com/swf/flvplayer.swf" type="application/x-shockwave-flash" />]]> </embed_code> </video> - <video id="74"> <public_hostid>1000000760</public_hostid> <duration>71.551</duration> <channel_id>1241817665482</channel_id> <creation_date>1241820827897</creation_date> <filename>95da48ed7fb11c8353a1efc8f13c9306ca030be5_1241817664594.flv</filename> <size>9875</size> <url>http://static.streamapi.com/video/100/000/076/0/95da48ed7fb11c8353a1efc8f13c9306ca030be5_1241817664594.flv</url> <embed_code><![CDATA[<embed height="240" width="320" flashVars="&file=http://static.streamapi.com/video/100/000/076/0/95da48ed7fb11c8353a1efc8f13c9306ca030be5_1241817664594.flv&image=http://static.streamapi.com/video/100/000/076/0/95da48ed7fb11c8353a1efc8f13c9306ca030be5_1241817664594.flv.jpg&bufferlength=5&volume=10&autostart=false&icons=false&controlbar=bottom&fullscreen=true&dock=false" allowfullscreen="true" allowscriptaccess="always" quality="high" name="mpl" id="mpl" style="" src="https://streamapi.com/swf/flvplayer.swf" type="application/x-shockwave-flash" />]]> </embed_code> </video> </videos> <code>0</code> </streamapi>

Status Codes

Code	Description
1	Missing required parameter(s)
8	No user found
46	No session found
100	Unknown Error
200	Invalid API key
202	Invalid sig (or signature) value
203	Invalid request ID value

8) Get layout themes

Description

List layout themes

URL

http://api.streamapi.com/service/theme/list

Method

GET

Parameters

Required

• key
• sig
• rid

Optional

• None

Example response

<?xml version="1.0" encoding="UTF-8" ?> - <streamapi> - <themes> - <theme id="58"> <name>4:3, 2 Guests</name> <width>514</width> <height>538</height> <layout_path>/themes/1/theme_2d47d33e-82a5-11de-b601-553e3e471fe9.xml</layout_path> <skin_path>/themes/1/skin_2d47d33e-82a5-11de-b601-553e3e471fe9.xml</skin_path> </theme> - <theme id="74"> <name>16x9, 2 Guests</name> <width>641</width> <height>538</height> <layout_path>/themes/1/theme_2c976efd-82a5-11de-b601-553e3e471fe9.xml</layout_path> <skin_path>/themes/1/skin_2c976efd-82a5-11de-b601-553e3e471fe9.xml</skin_path> </theme> </themes> <code>0</code> </streamapi>

Status Codes

Code	Description
1	Missing required parameter(s)
46	No session found
100	Unknown Error
200	Invalid API key
202	Invalid sig (or signature) value
203	Invalid request ID value