Ant Media Broadcasts API
The Broadcasts API from Ant Media — 45 operation(s) for broadcasts.
The Broadcasts API from Ant Media — 45 operation(s) for broadcasts.
openapi: 3.0.1
info:
title: Ant Media Server REST API Reference Broadcasts API
description: Ant Media Server REST API Reference
contact:
name: Ant Media Info
url: https://antmedia.io
email: contact@antmedia.io
license:
name: Apache 2.0
url: http://www.apache.org
version: V2.0
servers:
- url: https://test.antmedia.io:5443/Sandbox/rest/
description: test server
tags:
- name: Broadcasts
paths:
/v2/broadcasts/{id}/rtmp-endpoint:
post:
summary: Adds a third party RTMP end point to the stream
description: It supports adding after broadcast is started. Resolution can be specified to send a specific adaptive resolution. If an URL is already added to a stream, trying to add the same RTMP URL will return false.
operationId: addEndpointV3
parameters:
- name: id
in: path
description: Broadcast id
required: true
schema:
type: string
- name: resolutionHeight
in: query
description: 'Resolution height of the broadcast that is wanted to send to the RTMP endpoint. '
schema:
type: integer
format: int32
requestBody:
description: RTMP url of the endpoint that stream will be republished. If required, please encode the URL
content:
application/json:
schema:
$ref: '#/components/schemas/Endpoint'
required: true
responses:
'200':
description: Add RTMP endpoint response
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
delete:
summary: Remove third-party RTMP end point from the stream
description: For the stream that is broadcasting, it will stop immediately.
operationId: removeEndpointV2
parameters:
- name: id
in: path
description: Broadcast id
required: true
schema:
type: string
- name: endpointServiceId
in: query
description: RTMP url of the endpoint that will be stopped.
required: true
schema:
type: string
- name: resolutionHeight
in: query
description: Resolution specifier if endpoint has been added with resolution. Only applicable if user added RTMP endpoint with a resolution speficier. Otherwise won't work and won't remove the endpoint.
schema:
type: integer
format: int32
responses:
'200':
description: Remove RTMP endpoint response
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
/v2/broadcasts/{stream_id}/id3:
post:
description: Add ID3 data to HLS stream at the moment
operationId: addID3Data
parameters:
- name: stream_id
in: path
description: the id of the stream
required: true
schema:
type: string
requestBody:
description: ID3 data.
content:
application/json:
schema:
type: string
responses:
default:
description: default response
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
/v2/broadcasts/{stream_id}/sei:
post:
description: Add SEI data to HLS stream at the moment
operationId: addSEIData
parameters:
- name: stream_id
in: path
description: the id of the stream
required: true
schema:
type: string
requestBody:
description: SEI data.
content:
application/json:
schema:
type: string
responses:
default:
description: default response
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
/v2/broadcasts/{id}/subtrack:
post:
summary: Add a subtrack to a main track (broadcast)
description: Adds a subtrack to a main track (broadcast).
operationId: addSubTrack
parameters:
- name: id
in: path
description: Broadcast id(main track)
required: true
schema:
type: string
- name: id
in: query
description: Subtrack Stream Id
required: true
schema:
type: string
responses:
'200':
description: Result of adding a subtrack
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
delete:
summary: Delete a subtrack from a main track (broadcast)
description: Deletes a subtrack from a main track (broadcast).
operationId: removeSubTrack
parameters:
- name: id
in: path
description: Broadcast id(main track)
required: true
schema:
type: string
- name: id
in: query
description: Subtrack Stream Id
required: true
schema:
type: string
responses:
'200':
description: Result of deleting a subtrack
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
/v2/broadcasts/{id}/subscribers:
post:
summary: Add Subscriber to the requested stream
description: Adds a subscriber to the requested stream. If the subscriber's type is 'publish', they can also play the stream, which is critical in conferencing. If the subscriber's type is 'play', they can only play the stream. If 'b32Secret' is not set, it will default to the AppSettings. The length of 'b32Secret' should be a multiple of 8 and use base32 characters A?Z, 2?7.
operationId: addSubscriber
parameters:
- name: id
in: path
description: The id of the stream
required: true
schema:
type: string
requestBody:
description: Subscriber to be added to this stream
content:
application/json:
schema:
$ref: '#/components/schemas/Subscriber'
required: true
responses:
'200':
description: Result of adding a subscriber
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
delete:
summary: Removes all subscribers related to the requested stream
description: Deletes all subscriber data associated with the specified stream including ConnectionEvents.
operationId: revokeSubscribers
parameters:
- name: id
in: path
description: the id of the stream
required: true
schema:
type: string
responses:
'200':
description: Result of removing all subscribers
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
/v2/broadcasts/{id}/subscribers/{sid}/block/{seconds}/{type}:
put:
summary: Block specific subscriber
description: Blocks a specific subscriber, enhancing security especially when used with TOTP streaming. The subscriber is blocked for a specified number of seconds from the moment this method is called.
operationId: blockSubscriber
parameters:
- name: id
in: path
description: the id of the stream
required: true
schema:
type: string
- name: sid
in: path
description: the id of the subscriber
required: true
schema:
type: string
- name: seconds
in: path
description: seconds to block the user
required: true
schema:
type: integer
format: int32
- name: type
in: path
description: block type it can be 'publish', 'play' or 'publish_play'
required: true
schema:
type: string
responses:
'200':
description: Result of blocking the subscriber
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
/v2/broadcasts/create:
post:
description: Creates a Broadcast, IP Camera or Stream Source and returns the full broadcast object with rtmp address and other information. The different between Broadcast and IP Camera or Stream Source is that Broadcast is ingested by Ant Media ServerIP Camera or Stream Source is pulled by Ant Media Server
operationId: createBroadcast
parameters:
- name: autoStart
in: query
description: Only effective if stream is IP Camera or Stream Source. If it's true, it starts automatically pulling stream. Its value is false by default
schema:
type: boolean
requestBody:
description: Broadcast object. Set the required fields, it may be null as well.
content:
application/json:
schema:
$ref: '#/components/schemas/Broadcast'
responses:
'400':
description: If stream id is already used in the data store, it returns error
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
'200':
description: Returns the created stream
content:
application/json:
schema:
$ref: '#/components/schemas/Broadcast'
tags:
- Broadcasts
/v2/broadcasts/{id}:
get:
description: Get broadcast object
operationId: getBroadcast
parameters:
- name: id
in: path
description: id of the broadcast
required: true
schema:
type: string
responses:
'200':
description: Return the broadcast object
content:
application/json:
schema:
$ref: '#/components/schemas/Broadcast'
'404':
description: Broadcast object not found
tags:
- Broadcasts
put:
description: 'Updates the Broadcast objects fields if it''s not null. The updated fields are as follows: name, description, userName, password, IP address, streamUrl of the broadcast. It also updates the social endpoints'
operationId: updateBroadcast
parameters:
- name: id
in: path
description: Broadcast id
required: true
schema:
type: string
requestBody:
description: Broadcast object with the updates
content:
application/json:
schema:
$ref: '#/components/schemas/BroadcastUpdate'
responses:
'200':
description: If it's updated, success field is true. If it's not updated, success field is false.
tags:
- Broadcasts
delete:
summary: Delete broadcast from data store and stop if it's broadcasting
operationId: deleteBroadcast
parameters:
- name: id
in: path
description: ' Id of the broadcast'
required: true
schema:
type: string
responses:
'200':
description: If it's deleted, success is true. If it's not deleted, success if false.
content:
application/json:
schema:
$ref: '#/components/schemas/Broadcast'
tags:
- Broadcasts
/v2/broadcasts:
delete:
description: Delete multiple broadcasts from data store and stop if they are broadcasting
operationId: deleteBroadcastsBulk
parameters:
- name: ids
in: query
description: Comma-separated stream Ids
required: true
schema:
type: string
responses:
'200':
description: If it's deleted, success is true. If it's not deleted, success if false.
content:
application/json:
schema:
$ref: '#/components/schemas/Broadcast'
tags:
- Broadcasts
/v2/broadcasts/{id}/subscribers/{sid}:
delete:
summary: Delete specific subscriber from data store
description: Deletes a specific subscriber from the data store for the selected stream.
operationId: deleteSubscriber
parameters:
- name: id
in: path
description: the id of the stream
required: true
schema:
type: string
- name: sid
in: path
description: the id of the subscriber
required: true
schema:
type: string
responses:
'200':
description: Result of deleting the subscriber
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
/v2/broadcasts/{id}/recording/{recording-status}:
put:
summary: Set stream specific recording setting
description: This setting overrides the general Mp4 and WebM Muxing Setting for a specific stream.
operationId: enableRecording
parameters:
- name: id
in: path
description: the id of the stream
required: true
schema:
type: string
- name: recording-status
in: path
description: Change recording status. If true, starts recording. If false stop recording
required: true
schema:
type: boolean
- name: recordType
in: query
description: 'Record type: ''mp4'' or ''webm''. It''s optional parameter.'
schema:
type: string
- name: resolutionHeight
in: query
description: 'Resolution height of the broadcast that is wanted to record. '
schema:
type: integer
format: int32
responses:
'200':
description: Result of setting stream specific recording
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
/v2/broadcasts/active-live-stream-count:
get:
summary: Return the active live streams
description: Retrieves the currently active live streams.
operationId: getAppLiveStatistics
responses:
'200':
description: Active live streams
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleStat'
tags:
- Broadcasts
/v2/broadcasts/list/{offset}/{size}:
get:
description: Gets the broadcast list from database. It returns max 50 items at a time
operationId: getBroadcastList
parameters:
- name: offset
in: path
description: This is the offset of the list, it is useful for pagination. If you want to use sort mechanism, we recommend using Mongo DB.
required: true
schema:
type: integer
format: int32
- name: size
in: path
description: Number of items that will be fetched. If there is not enough item in the datastore, returned list size may less then this value
required: true
schema:
type: integer
format: int32
- name: type_by
in: query
description: Type of the stream. Possible values are "liveStream", "ipCamera", "streamSource", "VoD"
schema:
type: string
- name: sort_by
in: query
description: Field to sort. Possible values are "name", "date", "status"
schema:
type: string
- name: order_by
in: query
description: '"asc" for Ascending, "desc" Descending order'
schema:
type: string
- name: search
in: query
description: Search parameter, returns specific items that contains search string
schema:
type: string
responses:
default:
description: default response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Broadcast'
tags:
- Broadcasts
/v2/broadcasts/{id}/broadcast-statistics:
get:
summary: Get the broadcast live statistics
description: Retrieves live statistics of the broadcast, including total RTMP watcher count, total HLS watcher count, and total WebRTC watcher count.
operationId: getBroadcastStatistics
parameters:
- name: id
in: path
description: the id of the stream
required: true
schema:
type: string
responses:
'200':
description: Broadcast live statistics
content:
application/json:
schema:
$ref: '#/components/schemas/BroadcastStatistics'
tags:
- Broadcasts
/v2/broadcasts/total-broadcast-statistics:
get:
summary: Get total broadcast live statistics
description: Retrieves total live statistics of the broadcast, including total HLS watcher count and total WebRTC watcher count.
operationId: getBroadcastTotalStatistics
responses:
'200':
description: Total broadcast live statistics
content:
application/json:
schema:
$ref: '#/components/schemas/BroadcastStatistics'
tags:
- Broadcasts
/v2/broadcasts/{streamId}/ip-camera-error:
get:
summary: Get IP Camera Error after connection failure
description: Checks for an error after a connection failure with an IP camera. Returning true indicates an error; false indicates no error.
operationId: getCameraErrorV2
parameters:
- name: streamId
in: path
description: StreamId of the IP Camera Streaming.
required: true
schema:
type: string
responses:
'200':
description: IP Camera error status
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
/v2/broadcasts/{id}/connection-events/{offset}/{size}:
get:
summary: 'Retrieve all subscriber statistics of the requested stream. Deprecated '
description: Fetches comprehensive statistics for all subscribers of the specified stream.
operationId: getConnectionEvents
parameters:
- name: id
in: path
description: the id of the stream
required: true
schema:
type: string
- name: offset
in: path
description: the starting point of the list
required: true
schema:
type: integer
format: int32
- name: size
in: path
description: size of the return list (max:50 )
required: true
schema:
type: integer
format: int32
- name: subscriberId
in: query
description: subscriberId to filter the connections events
schema:
type: string
responses:
'200':
description: List of subscriber statistics
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriberStats'
tags:
- Broadcasts
/v2/broadcasts/{id}/detections/{offset}/{size}:
get:
summary: Retrieve detected objects from the stream
description: Fetches detected objects from the stream, using specified offset and size parameters.
operationId: getDetectionListV2
parameters:
- name: id
in: path
description: the id of the stream
required: true
schema:
type: string
- name: offset
in: path
description: starting point of the list
required: true
schema:
type: integer
format: int32
- name: size
in: path
description: total size of the return list
required: true
schema:
type: integer
format: int32
responses:
'200':
description: List of detected TensorFlow objects
content:
application/json:
schema:
$ref: '#/components/schemas/TensorFlowObject'
tags:
- Broadcasts
/v2/broadcasts/duration:
get:
description: Gets the durations of the stream url in milliseconds
operationId: getDuration
parameters:
- name: url
in: query
description: Url of the stream that its duration will be returned
required: true
schema:
type: string
responses:
'200':
description: 'If operation is successful, duration will be in dataId field and success field is true. If it''s failed, errorId has the error code(-1: duration is not available, -2: url is not opened, -3: cannot get stream info) and success field is false'
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
/v2/broadcasts/{id}/jwt-token:
get:
description: Generates JWT token for specified stream. It's not required to let the server generate JWT. Generally JWT tokens should be generated on the client side.
operationId: getJwtTokenV2
parameters:
- name: id
in: path
description: The id of the stream
required: true
schema:
type: string
- name: expireDate
in: query
description: The expire time of the token. It's in unix timestamp seconds.
required: true
schema:
type: integer
format: int64
- name: type
in: query
description: 'Type of the JWT token. It may be play or publish '
required: true
schema:
type: string
- name: roomId
in: query
description: 'Room Id that token belongs to. It''s not mandatory '
schema:
type: string
responses:
'200':
description: Returns token
content:
application/json:
schema:
$ref: '#/components/schemas/Token'
'400':
description: When there is an error in creating token
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
/v2/broadcasts/{id}/detections/count:
get:
summary: Get total number of detected objects
description: Retrieves the total count of objects detected.
operationId: getObjectDetectedTotal
parameters:
- name: id
in: path
description: id of the stream
required: true
schema:
type: string
responses:
'200':
description: Total number of detected objects
content:
application/json:
schema:
type: integer
format: int64
tags:
- Broadcasts
/v2/broadcasts/{id}/ip-camera/device-profiles:
get:
summary: Get the Profile List for an ONVIF IP Camera
description: Retrieves the profile list for an ONVIF IP camera.
operationId: getOnvifDeviceProfiles
parameters:
- name: id
in: path
description: The id of the IP Camera
required: true
schema:
type: string
responses:
'200':
description: Profile list for the ONVIF IP camera
content:
application/json:
schema:
type: string
tags:
- Broadcasts
/v2/broadcasts/{id}/rtmp-to-webrtc-stats:
get:
summary: Get RTMP to WebRTC Path Stats
description: Retrieves general statistics for the RTMP to WebRTC path.
operationId: getRTMPToWebRTCStats
parameters:
- name: id
in: path
description: the id of the stream
required: true
schema:
type: string
responses:
'200':
description: RTMP to WebRTC path statistics
content:
application/json:
schema:
$ref: '#/components/schemas/RTMPToWebRTCStats'
tags:
- Broadcasts
/v2/broadcasts/{id}/stream-info:
get:
summary: Get stream information
description: Returns the stream information including width, height, bitrates, and video codec.
operationId: getStreamInfo
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Stream information
content:
application/json:
schema:
type: string
tags:
- Broadcasts
/v2/broadcasts/{id}/subscribers/{sid}/totp:
get:
description: 'Return TOTP for the subscriberId, streamId, type. This is a helper method. You can generate TOTP on your end.If subscriberId is not in the database, it generates TOTP from the secret in the AppSettings. Secret code is for the subscriberId not in the database secretCode = Base32.encodeAsString({secretFromSettings(publishsecret or playsecret according to the type)} + {subscriberId} + {streamId} + {type(publish or play)} + {Number of X to have the length multiple of 8}''+'' means concatenating the strings. There is no explicit ''+'' in the secretCode '
operationId: getTOTP
parameters:
- name: id
in: path
description: The id of the stream that TOTP will be generated
required: true
schema:
type: string
- name: sid
in: path
description: 'The id of the subscriber that TOTP will be generated '
required: true
schema:
type: string
- name: type
in: query
description: The type of token. It's being used if subscriber is not in the database. It can be publish, play
schema:
type: string
responses:
default:
description: default response
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
/v2/broadcasts/{id}/token:
get:
description: Generates random one-time token for specified stream
operationId: getTokenV2
parameters:
- name: id
in: path
description: The id of the stream
required: true
schema:
type: string
- name: expireDate
in: query
description: The expire time of the token. It's in unix timestamp seconds
required: true
schema:
type: integer
format: int64
- name: type
in: query
description: 'Type of the token. It may be play or publish '
required: true
schema:
type: string
- name: roomId
in: query
description: 'Room Id that token belongs to. It''s not mandatory '
schema:
type: string
responses:
'200':
description: Returns token
content:
application/json:
schema:
$ref: '#/components/schemas/Token'
'400':
description: When there is an error in creating token
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
/v2/broadcasts/count:
get:
summary: Get the total number of broadcasts
description: Retrieves the total number of broadcasts.
operationId: getTotalBroadcastNumberV2
responses:
'200':
description: Total number of broadcasts
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleStat'
tags:
- Broadcasts
/v2/broadcasts/count/{search}:
get:
summary: Get the number of broadcasts based on search criteria
description: Retrieves the number of broadcasts matching the specified search criteria.
operationId: getTotalBroadcastNumberV2_1
parameters:
- name: search
in: path
description: 'Search parameter to get the number of items including it '
required: true
schema:
type: string
responses:
'200':
description: Number of broadcasts for searched items
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleStat'
tags:
- Broadcasts
/v2/broadcasts/{stream_id}/webrtc-client-stats/{offset}/{size}:
get:
summary: Get WebRTC Client Statistics
description: Retrieves WebRTC client statistics, including audio bitrate, video bitrate, target bitrate, video sent period, etc.
operationId: getWebRTCClientStatsListV2
parameters:
- name: offset
in: path
description: offset of the list
required: true
schema:
type: integer
format: int32
- name: size
in: path
description: Number of items that will be fetched
required: true
schema:
type: integer
format: int32
- name: stream_id
in: path
description: the id of the stream
required: true
schema:
type: string
responses:
'200':
description: WebRTC client statistics
content:
application/json:
schema:
$ref: '#/components/schemas/WebRTCClientStats'
tags:
- Broadcasts
/v2/broadcasts/webrtc-receive-low-level-stats:
get:
summary: Get WebRTC Low Level Receive Stats
description: Retrieves general statistics for WebRTC low level receive operations.
operationId: getWebRTCLowLevelReceiveStats
responses:
'200':
description: WebRTC low level receive statistics
content:
application/json:
schema:
$ref: '#/components/schemas/WebRTCReceiveStats'
tags:
- Broadcasts
/v2/broadcasts/webrtc-send-low-level-stats:
get:
summary: Get WebRTC Low Level Send Stats
description: Retrieves general statistics for WebRTC low level send operations.
operationId: getWebRTCLowLevelSendStats
responses:
'200':
description: WebRTC low level send statistics
content:
application/json:
schema:
$ref: '#/components/schemas/WebRTCSendStats'
tags:
- Broadcasts
/v2/broadcasts/import-to-stalker:
post:
summary: Import Live Streams to Stalker Portal
description: Imports live streams into the Stalker Portal.
operationId: importLiveStreams2StalkerV2
responses:
'200':
description: Import operation result
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
tags:
- Broadcasts
/v2/broadcasts/{id}/subscriber-stats/list/{offset}/{size}:
get:
summary: 'Retrieve all subscriber statistics of the requested stream. Deprecated use connection-events method. '
description: Fetches comprehensive statistics for all subscribers of the specified stream. Deprecated use connection-events method. This method is kept for backward compatibility and getting old records. New records saved and retrieved with connection-events method because there is a schema design causes performance issues
operationId: listSubscriberStatsV2
parameters:
- name: id
in: path
description: the id of the stream
required: true
schema:
type: string
- name: offset
in: path
description: the starting point of the list
required: true
schema:
type: integer
format: int32
- name: size
in: path
description: size of the return list (max:50 )
required: true
schema:
type: integer
format: int32
responses:
'200':
description: List of subscriber statistics
content:
application/json:
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ant-media/refs/heads/main/openapi/ant-media-broadcasts-api-openapi.yml