API Reference | HotMic

REST endpoints for streams, users, clips, and tags. All requests are authenticated with an API key issued by HotMic.

To use the HotMic Public API, you need to use a public API key provided by HotMic.

Retrieve 1 or More Streams

GEThttps://public-api.hotmic.io/streams

Retrieve Stream(s) Endpoint

Get one or more streams.

Query Parameters

Name	Type	Required	Description
limit	Integer	Optional	Limits the number of results returned by the query. Defaults to 100.
state	string	Optional	Filter results to only include streams with a given state. Can be: "SCHEDULED", "LIVE", "ENDED", or "VOD"
userId	String	Optional	Filter results to only include streams with a certain userId.
ids	String	Optional	Filter results to only include 1 or more streams by id. If passing multiple ids, separate them by an underscore _. (example: abc-123_def-456 would filter for 2 streams "abc-123" and "def-456").
orderBy	string	Optional	The field to order by, ascending by default
desc	Boolean	Optional	If true, order by descending instead of ascending.
cursor	string	Optional	This filters the results to only return the next results after this cursor, up to the limit. Typically used for pagination, this is the last result that will be ignored based on the orderBy field. So if you are sorting by ids, and you have 5 users with id 1,2,3,4,5: passing cursor=2 limit=2 would return 3,4. Do not use combined with "skip".
skip	Integer	Optional	When paginating, how many results to skip. If using skip 30 limit 10, you would get results 31 to 40. Do not use combined with "cursor".
pagination	string	Optional	Defaults to "skip". If this is set to "cursor", then the "next" result on the link will always return the correct next paginated result using a cursor.

Header Parameters

Name	Type	Required	Description
x-api-key	String	Required	The API key provided to you by HotMic.

Examples

curl --location --request GET 'https://public-api.hotmic.io/streams?limit=Integer&state=string&userId=String&ids=String&orderBy=string&desc=Boolean&cursor=string&skip=Integer&pagination=string' \
--header 'Accept: application/json' \
--header 'x-api-key: String'

var request = require('request');
var options = {
   'method': 'GET',
   'url': 'https://public-api.hotmic.io/streams?limit=Integer&state=string&userId=String&ids=String&orderBy=string&desc=Boolean&cursor=string&skip=Integer&pagination=string',
   'headers': {
      'Accept': 'application/json',
      'x-api-key': 'String'
   }
};
request(options, function (error, response) {
   if (error) throw new Error(error);
   console.log(response.body);
});

var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("x-api-key", "String");

var requestOptions = {
   method: 'GET',
   headers: myHeaders,
   redirect: 'follow'
};

fetch("https://public-api.hotmic.io/streams?limit=Integer&state=string&userId=String&ids=String&orderBy=string&desc=Boolean&cursor=string&skip=Integer&pagination=string", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

import requests

url = "https://public-api.hotmic.io/streams?limit=Integer&state=string&userId=String&ids=String&orderBy=string&desc=Boolean&cursor=string&skip=Integer&pagination=string"

payload={}
headers = {
   'Accept': 'application/json',
   'x-api-key': 'String'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "net/http"

url = URI("https://public-api.hotmic.io/streams?limit=Integer&state=string&userId=String&ids=String&orderBy=string&desc=Boolean&cursor=string&skip=Integer&pagination=string")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = "application/json"
request["x-api-key"] = "String"

response = https.request(request)
puts response.read_body

Responses

{
  "links": {
    "next": "https://public-api.hotmic.io/streams?skip=3&limit=2&orderBy=title",
    "self": "https://public-api.hotmic.io/streams?skip=1&limit=2&orderBy=title"
  },
  "limit": 2,
  "count": 2,
  "results": [
    {
      "_id": "82052303-2a846-45b9-nuo5-3e3447208xece",
      "user_id": "a4erf186-6824-4asf4d-a33e-agsab1b776",
      "title": "111 Live",
      "thumbnail": "https://d1h34rji.cloudfront.net/thumbnails/default_thumbnail_turner.png",
      "scheduled_date": "2022-08-16T22:27:08Z",
      "state": "VOD",
      "type": "broadcast",
      "description": "",
      "event_id": "bb1asdfd-8d20-4881-a675-0433e43340883",
      "live_date": "2022-08-16T22:28:36Z",
      "duration": 31.295,
      
      "user": {
        "_id": "a5fd6-6824-44erafd-a33e-bbc1rjf89776",
        "followers": 0,
        "display_name": "BleacherBob",
        "profile_pic": "https://d1h34rji.cloudfront.net/apps/09c935f55d90da6f455c/images/a533e186-d38bf4_profile.png"
      },
      "last_updated": "2022-08-16T22:29:17Z",
      "video_url": "https://d1h34rji.cloudfront.net/recorded-streams/chris-9073/82052303447a18ece/chris.m3u8"
    },
    {
      "_id": "85a2easd8-02cc-4824e-a3ff7-0gt4373",
      "user_id": "a52adsff4-4erg-bbc15ab1b776",
      "title": "123",
      "thumbnail": "https://d1h34rji.cloudfront.net/thumbnails/default_thumbnails.png",
      "scheduled_date": "2022-08-17T15:22:19Z",
      "state": "VOD",
      "type": "broadcast",
      "description": "",
      "event_id": "742f12d7-b875-463c2-a034refeafe7c",
      "live_date": "2022-08-17T15:24:25Z",
      "duration": 71.351,
      "user": {
        "_id": "a5awef4-6824-43ed-a33e-43erff776",
        "followers": 0,
        "display_name": "BleacherBob",
        "profile_pic": "https://d1h34rji.cloudfront.net/apps/09f455c/images/a533e76_8acfd38bf4_profile.png"
      },
      "last_updated": "2022-08-17T16:02:24Z",
      "video_url": "https://d1h34rji.cloudfront.net/recorded-streams/chr03/85a2e6873/video.m3u8",
      "video_mp4_url": "https://example.com/file.mp4",
      "video_dash_url": "https://example.com/manifest.mpd",
      "video_orientation": "portrait",
      "tags": [
        {
          "uuid": "48681e1e-fda3-438e-990c-8f925964f410",
          "type": "general",
          "displayName": "11"
        },
        {
          "uuid": "864e2094-9865-4f5b-8891-391fe9cfa23f",
          "type": "general",
          "displayName": "3 rsadf adsf"
        }
      ],
    }
  ]
}

Example Requests

Get all Streams (default limit)

https://public-api.hotmic.io/streams

Get set of 100 Streams

https://public-api.hotmic.io/streams?limit=1000

Get next set of 1000 Streams (provided by “$.links.next” in response

https://public-api.hotmic.io/streams?cursor=a3113c5b-26f5-4704-aa43-288446d250b6&limit=1000

Get specific Streams by Stream ID

https://public-api.hotmic.io/streams?ids=e35a851b-e161-46b7-a921-f6899ccb9cc0_0e246a7b-1a14-4028-aac6-a2f0433bd8c7

Get all Streams for specific User ID (default limit)

https://public-api.hotmic.io/streams?userId=e35a851b-e161-46b7-a921-f6899ccb9cc0

Get all Streams updated since last check

https://public-api.hotmic.io/streams?orderBy=last_updated&cursor=2022-10-13T17:00:08Z

Response

Returns the stream object if the update succeeded. Returns an error if there the update fails.

_id: string - the id of the streams
user_id: string - the user_id of the host
title: string - the title of the stream
thumbnail: string - the url to the thumbnail image
scheduled_date: string - the datetime a stream is scheduled
state: string - can be "SCHEDULED" "LIVE" "ENDED" or "VOD"
deleted: boolean - whether a stream was deleted "true" if deleted
duration: integer - length of VOD in seconds
tags: array - an array of objects
video_url: string - url for the live hls stream when live and vod hls stream when the state is VOD. This url for the live stream is available when the stream is created, but will not be a valid working HLS until the creator broadcasts HLS. The URL will not change until it is VOD, at which time the video_url will return the VOD url.
video_mp4_url: string - the url of a mp4 download link, available after the stream has in the VOD state.
video_dash_url: string - url for the live dash stream when live and vod dash stream when the state is VOD. This url for the live stream is available when the stream is created, but will not be a valid working dash until the creator broadcasts dash. The URL will not change until it is VOD, at which time the video_dash_url will return the VOD url.
video_orientation: string - null or "landscape" for horizontal video. "portrait" for vertical video.
description: string - a description of the stream
event_id: - the id of the event a stream is associated to. Only useful if you are creating mutiple streams per event.
type: string - the type of stream
live_date: string - the datetime the stream was set to "LIVE"
last_updated: string - the datetime the stream was edited
invite_link: string - the link stored by HotMic to the stream
stream_key: string - a key, generally matching the _id for the stream, that identifies this for some ingestion processes (LIVE AS OF OCT 17, 2025)
user: object with:
- _id: string - the id of the user
- followers: string - the number of followers of the user if using HotMic following tools
- display_name: string - the name of the user to display to others
- profile_pic: string - the url to the profile pic of the user
- tags: array - 1 ore more tags associated with the user

Update a Stream

PUThttps://public-api.hotmic.io/streams/:id

Update Stream Endpoint

Update stream information, such as title or invite link.

Path Parameters

Name	Type	Required	Description
id	string	Required	ID of the stream to modify

Header Parameters

Name	Type	Required	Description
x-api-key	string	Required	The API key provided to you by HotMic.

Body Parameters

Name	Type	Required	Description
title	string	Optional	The title of the stream
user_id	string	Optional	Update the user_id of the owner of the stream in HotMic. Note, this must be a valid HotMic user_id.
thumbnail	string	Optional	Update the url to the stream thumbnail of used in HotMic. Note: the url must be publically accessible if updating in this way.
scheduled_date	string	Optional	Update the scheduled_date of the stream. Dates are in ISO-8601 format, for example: "2019-09-08T00:00:00.000+00:00".
description	string	Optional	Update the description of the event.
invite_link	string	Optional	The invite link is the link to the stream. If you generate a link for the event, use this to update the link for the hosts to see. This doesn't change the link to the event itself, rather the link for the hosts to view.

Examples

curl --location --request PUT 'https://public-api.hotmic.io/streams/:id' \
--header 'Accept: application/json' \
--header 'x-api-key: string' \
--data-raw '{"title":"string","user_id":"string","thumbnail":"string","scheduled_date":"string","description":"string","invite_link":"string"}'

var request = require('request');
var options = {
   'method': 'PUT',
   'url': 'https://public-api.hotmic.io/streams/:id',
   'headers': {
      'Accept': 'application/json',
      'x-api-key': 'string'
   },
   body: '{"title":"string","user_id":"string","thumbnail":"string","scheduled_date":"string","description":"string","invite_link":"string"}'

};
request(options, function (error, response) {
   if (error) throw new Error(error);
   console.log(response.body);
});

var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("x-api-key", "string");

var raw = "{\"title\":\"string\",\"user_id\":\"string\",\"thumbnail\":\"string\",\"scheduled_date\":\"string\",\"description\":\"string\",\"invite_link\":\"string\"}";

var requestOptions = {
   method: 'PUT',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://public-api.hotmic.io/streams/:id", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

import requests

url = "https://public-api.hotmic.io/streams/:id"

payload = "{\"title\":\"string\",\"user_id\":\"string\",\"thumbnail\":\"string\",\"scheduled_date\":\"string\",\"description\":\"string\",\"invite_link\":\"string\"}"
headers = {
   'Accept': 'application/json',
   'x-api-key': 'string'
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "net/http"

url = URI("https://public-api.hotmic.io/streams/:id")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Accept"] = "application/json"
request["x-api-key"] = "string"
request.body = "{\"title\":\"string\",\"user_id\":\"string\",\"thumbnail\":\"string\",\"scheduled_date\":\"string\",\"description\":\"string\",\"invite_link\":\"string\"}"

response = https.request(request)
puts response.read_body

Responses

{
  "_id": "82057643-2a46-45b9-96f5-3e3447a18ece",
  "user_id": "a533e987-6824-43ed-a33e-bbc15ab1b776",
  "title": "streams are great",
  "thumbnail": "https://d1h8hiv1w8cbe.cloudfront.net/thumbnails/thu.png",
  "scheduled_date": "2022-08-16T22:27:08Z",
  "state": "VOD",
  "type": "broadcast",
  "description": "",
  "hls_url": "https://d1q6387gevjuox.cloudfront.net/chris-9073/a/chris-9073.m3u8",
  "event_id": "bbubiy6f7d-8d20-4881-a675-0433e0ba5883",
  "live_date": "2022-08-16T22:28:36Z",
  "duration": 31.295,
  "vod_url": "https://d9djhjg315vs.cloudfront.net/recorded-streams/chris-9073/82052303-2a46-45b9-96f5-3e3447a18ece/chris-9073.m3u8",
  "last_updated": "2022-08-16T22:29:17Z",
  "invite_link": "https://www.mylink.com"
}

Returns the stream object if the update succeeded. Returns an error if there the update fails.

Update a User

PUThttps://public-api.hotmic.io/users/:id

Update User Endpoint

Update user information, such as their name or the default invite link for their profile.

Path Parameters

Name	Type	Required	Description
id	string	Required	The ID of the user to modify.

Header Parameters

Name	Type	Required	Description
x-api-key	string	Required	The API key provided to you by HotMic.

Body Parameters

Name	Type	Required	Description
name	string	Optional	The name of the user to modify
email	string	Optional	The email of the user to modify
default_invite_link	string	Optional	The default_invite_link of the user to modify
tags	Array	Optional	General tags are added, edited, and returned with the user object when it is returned in the API. This allows you to add information for future use.
authorized_stream_tags	Array	Optional	"authorized_stream_tags" define the tags a user can add to a stream. When adding a stream, a user can add tags to the stream from this list, and their selected tags will appear as stream tags.

Examples

curl --location --request PUT 'https://public-api.hotmic.io/users/:id' \
--header 'Accept: application/json' \
--header 'x-api-key: string' \
--data-raw '{"name":"string","email":"string","default_invite_link":"string"}'

var request = require('request');
var options = {
   'method': 'PUT',
   'url': 'https://public-api.hotmic.io/users/:id',
   'headers': {
      'Accept': 'application/json',
      'x-api-key': 'string'
   },
   body: '{"name":"string","email":"string","default_invite_link":"string"}'

};
request(options, function (error, response) {
   if (error) throw new Error(error);
   console.log(response.body);
});

var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("x-api-key", "string");

var raw = "{\"name\":\"string\",\"email\":\"string\",\"default_invite_link\":\"string\"}";

var requestOptions = {
   method: 'PUT',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://public-api.hotmic.io/users/:id", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

import requests

url = "https://public-api.hotmic.io/users/:id"

payload = "{\"name\":\"string\",\"email\":\"string\",\"default_invite_link\":\"string\"}"
headers = {
   'Accept': 'application/json',
   'x-api-key': 'string'
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "net/http"

url = URI("https://public-api.hotmic.io/users/:id")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Accept"] = "application/json"
request["x-api-key"] = "string"
request.body = "{\"name\":\"string\",\"email\":\"string\",\"default_invite_link\":\"string\"}"

response = https.request(request)
puts response.read_body

Responses

{
  "_id": "079giuheac-d39a-4cc9-8997-d2kugi3da9",
  "name": "Friendly Host",
  "email": "host1@hotmic.io",
  "default_invite_link": "https://www.yourapplink.com/host"
}

Create User

POSThttps://public-api.hotmic.io/users/

Create User Endpoint

Creates a new user

Header Parameters

Name	Type	Required	Description
x-api-key	string	Required	The API key provided to you by HotMic.

Body Parameters

Name	Type	Required	Description
name	string	Required	The name of the user to modify
email	string	Optional	The email of the user to modify
default_invite_link	string	Optional	The default_invite_link of the user to modify
display_name	string	Optional	The display name, such as "superfan".
profile_pic	string	Optional	A URL to show for the user as a profile picture in chats and other areas.
tags	Array	Optional	General tags are added, edited, and returned with the user object when it is returned in the API. This allows you to add information for future use.
authorized_stream_tags	Array	Optional	"authorized_stream_tags" define the tags a user can add to a stream. When adding a stream, a user can add tags to the stream from this list, and their selected tags will appear as stream tags.

Examples

var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
   "id": "string"
});

var requestOptions = {
   method: 'GET',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://api.cakes.com", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

{
      "name": "Cake's name",
    }

Get All Users

GEThttps://public-api.hotmic.io/users/

Retrieve Users

Get a user by its ID

Query Parameters

Name	Type	Required	Description
limit	string	Optional	Limits the number of results returned by the query. Defaults to 100.
ids	string	Optional	Filter results to only include 1 or more streams by id. If passing multiple ids, separate them by an underscore _. (example: abc-123_def-456 would filter for 2 streams "abc-123" and "def-456").

Header Parameters

Name	Type	Required	Description
x-api-key	string	Required	The API key provided to you by HotMic.

Examples

var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
   "id": "String"
});

var requestOptions = {
   method: 'GET',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://api.cakes.com", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

{
      "name": "Cake's name",
    }