The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
room (required)
Room Object
Room Object
Field
Description
alias (required)
A user friendly unique identifier for the room. An empty string is required if you want the Streaming platform to generate an alias for your room.
description (required)
A description for the room.
name (required)
Unique name of the room.
options (required)
An array of options for the room. An empty array is required if there are no options.
type (optional)
Type of the room. Defaults to MultiPartyChat. Valid values include: DirectChat, MultiPartyChat, ModeratedChat and TownHall.
Creating a Room Response
The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.
The streaming platform was not able to authorize the provided credentials.
409 Conflict
already-exists
never
The room already exists.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
Request URI
Component
Description
urlEncodedRoomId (required)
URL encoded ID of the room
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Fetching a Room Response
The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not found
never
The room was not found.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
Request URI
Component
Description
urlEncodedRoomId (required)
ID of the room.
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Fetching members of a room Response
The API call returns an HTTP response per the following:
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not found
never
The room was not found.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
The streaming platform was not able to authorize the provided credentials.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedRoomId (required)
URL encoded ID of the room
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Deleting a Room Response
The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.
HTTP
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 15
4
5{"status":"ok"}
cURL
1{
2"status":"ok"
3}
Delete Room API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Room was successfully deleted.
400 Bad Request
varies
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
This API allows the caller to copy the active members (that is, the publishers) from one room to another room. Both the source and destination rooms must have previously been created.
A stream will be associated with the destination room which is a fork of the stream being published to the source room with the same content.
Fork a Room Request
Send a PUT request to the /pcast/room/<urlEncodedDestinationRoomId>/fork/<urlEncodedSourceRoomId> endpoint as shown:
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-length header.
Request URI
Component
Description
urlEncodedSourceRoomId (required)
URL encoded Room ID of the source room to fork from.
urlEncodedDestinationRoomId (required)
URL encoded Room ID of the destination room to fork into.
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
streamTags (optional)
An array of tags (strings) to apply to the destination streams.
streamCapabilities (optional)
An array of capabilities (strings) to apply to the newly forked stream.
options (optional)
An array of options (strings) for the room. Current valid options are: "force", "additive" and "keep-streams". The default behavior is not touch the stream(s) with matching session IDs that are already publishing to the destination room. With the "force" option, the stream(s) will be terminated and replaced. With the "additive" option, the stream(s) will be added to any existing members in the room. "keep-streams" removes the members but leaves the streams alive. Clients will receive the member update, but they are not securely terminated from the stream. In Phenix client implementations the default is to end the client stream, but customer client implementations may vary.
Fork a Room Response
The API call returns an HTTP response per the following:
Indicates an issue with the request. Eg: Options must be an array of strings.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not found
never
One or both of the source and destination rooms are not found.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-length header.
Request URI
Component
Description
urlEncodedRoomId (required)
ID of the room to kill.
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request Fields
Field
Description
reason (optional)
Arbitrary text string for recording why the stream was killed.
options (optional)
An array of options (strings). Valid options are: "keep-streams". "keep-streams" removes the members but leaves the streams alive. Clients will receive the member update, but they are not securely terminated from the stream. In Phenix client implementations the default is to end the client stream, but customer client implementations may vary.
Kill a Room Response
The API call returns an HTTP response per the following:
Indicates an issue with the request. Eg: Options must be an array of strings.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials or Field "reason" must be a string.
404 Not Found
not found
never
The room was not found.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error while processing the request.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedRoomId (required)
URL encoded ID of the room
Request URI Parameters
Parameter
Description
failIfLess (optional)
The number of required publishers that meet all criteria for the room.
withStreams (optional)
The number of streams required per publisher to be considered active in the room. Defaults to 1.
withScreenName (optional)
Only consider publishers with the given screen name. By default all screen names are considered.
Checking the State of a Room Response
The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.
HTTP
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 1
4
51
cURL
11
Health Room API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Number of publishers was successfully reported.
400 Bad Request
varies
never
Indicates an issue with the request.
404 Not Found
not-found
never
Indicates the room was not found.
4XX
varies
never
Indicates an issue with the request.
412 Precondition Failed
none
never
There is fewer than the required number of publishers.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
time-exceeded
once immediately, then exponential backoff
The request took to long to execute. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Room API Response fields
The response body is a text field with the number of publishers actively publishing a stream to the room.
Universal Live Manifest for a Room
This API allows to retrieve a live manifest of any type for a room. The URL is valid for the lifetime of the room and always points to the most recent stream in the room. In order for this to work, the stream must have enabled streaming capability.
Universal Live Manifest for a Room Request
Send a GET request to the /pcast/room/<urlEncodedRoomId>/<manifest> endpoint as shown:
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedRoomId (required)
URL encoded ID of the room
manifest (required)
The manifest ID such as live.m3u8 for HLS and live.mpd for DASH.
Request URI Parameters
Parameter
Description
streamToken (optional)
Streams protected with token-auth require a valid edge auth token to be provided. An edge auth token issued for the room ID or alias will grant access to the playlist for the room. Alternatively, if the origin stream ID is known, access can be restricted to just a stream itself.
Universal Live Manifest for a Room Response
The platform will return a successful response that contains the content of the manifest. The HTTP status code is set according to if the manifest exists or not.
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The room does not exist.
413 Payload Too Large
varies
never
One of the fields exceeds the limits. The size limit for messages is 1024 bytes. The total limit for all tags is 512 bytes. The screen name and mime type each must not exceed 128 bytes.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Request URI Parameters
Parameter
Description
limit (optional)
The number of messages to fetch. Defaults to 100.
beforeMessageId (optional)
The upper bound of the fetch range represented by another message ID.
afterMessageId (optional)
The lower bound of the fetch range represented by another message ID.
mimeTypes (optional)
Comma separated list of mime types. When provided only messages with the specified mime types will be returned. Note the search range is still the same so if no messages within the underlying range match then the result might be zero or less than the requested limit.
Fetching Messages Response
The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The room does not exist.
413 Payload Too Large
limit-too-large
never
Too many messages are requested. The maximal limit is 128 messages per request.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
504 Gateway Timeout
rate-limited
once immediately, then exponential backoff
The system is temporarily overloaded. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.
Encoding: Room ID may contain characters that are unsafe for URLs. Be sure to encode the RoomId in the URL path. For example, the URL encoding of `us-central#us-central` is `us-central%23us-central`
The Content-Length header is automatically populated by curl. If using another method to access the API, you must calculate and populate the Content-Length header.
Request URI
Component
Description
urlEncodedRoomId (required)
URL encoded ID of the room
Request Headers
Header
Description
Authorization (required)
Use HTTP Basic Authentication with your applicationId and secret
Purging Messages of a Room Response
The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the "status" field.
HTTP
1HTTP/1.1 200 OK
2Content-Type: application/json; charset=utf-8
3Content-Length: 32
4
5{"status":"ok","deletedCount":1}
cURL
1{
2"status":"ok",
3"deletedCount":1
4}
Purge Room Messages API Status Codes
HTTP
Status
Retry
Description
200 OK
ok
never
Room was successfully deleted.
400 Bad Request
varies
never
Indicates an issue with the request.
401 Unauthorized
unauthorized
never
The streaming platform was not able to authorize the provided credentials.
404 Not Found
not-found
never
The room does not exist.
4XX
varies
never
Indicates an issue with the request.
503 Service Unavailable
capacity
once
The system is temporarily overloaded. Please try again later.
5XX
varies
once immediately, then exponential backoff
A transient server error.
Error Responses: Please be aware that some server errors 5XX and request validation errors 400 and 401 may result in an arbitrary response body not encoded in JSON.