JSON API

All listed endpoints should be prefixed with (multistreamer-prefix)/api/v1, examples:

• example.com/api/v1/profile
• example.com/multistreamer/api/v1/profile (if running multistreamer under some prefix)

All endpoints except /auth require an authentication token, it should be passed by setting the Authentication: Bearer <token> header.

The /auth endpoint uses Authentication: Basic <base64-encoded username:password>

Endpoints

Endpoint	Description
GET /auth	Get authentication token
GET /profile	Get user info
GET /users	Get user list
GET /account	Get available accounts
GET /account/:id	Get single account
POST /account/:id	Update account
GET /stream	Get available streams
GET /stream/:id	Get single stream
POST /stream/:id	Update stream metadata, accounts, etc
PATCH /stream/:id	Start/stop stream pushers/pullers
POST /stream/:id/msg	Inject messages into a stream's chat

GET /auth

Returns the user's authentication token.

Example Request

curl -XGET --user username:pass http://example.com/api/v1/auth

Example Response

{
       "token" : "005DA1A3540565CEACCC"
}

GET /profile

Returns user info

Example Request

curl -XGET -H 'Authorization: Bearer 005DA1A3540565CEACCC' \
  http://example.com/api/v1/profile

Example Response

{
   "updated_at" : "2016-11-20 17:57:44",
   "id" : 1,
   "access_token" : "005DA1A3540565CEACCC",
   "username" : "john",
   "created_at" : "2016-11-20 17:57:44"
}

GET /user

Returns a list of users

Example Request

curl -XGET -H 'Authorization: Bearer 005DA1A3540565CEACCC' \
  http://127.0.0.1:8081/api/v1/user

Example Response

{
   "users" : [
      {
         "access_token" : "005DA1A3540565CEACCC",
         "id" : 1,
         "username" : "john"
      },
      {
         "username" : "test",
         "id" : 2
      }
   ]
}

GET /account

Returns a list of accounts the user can access

Example Request

 curl -XGET -H 'Authorization: Bearer 005DA1A3540565CEACCC' \
   http://example.com/api/v1/account

Example Response

{
   "accounts" : [
      {
         "slug" : "jprjrdev",
         "created_at" : "2017-03-19 15:10:15",
         "ffmpeg_args" : "-c:v copy -c:a aac -ac 2 -ab 96k",
         "name" : "jprjrdev",
         "network" : "twitch",
         "id" : 14,
         "settings" : {},
         "shares" : [
            {
               "user" : {
                  "username" : "test",
                  "id" : 2
               }
            }
         ],
         "updated_at" : "2017-03-19 15:10:15",
         "user_id" : 1
      },
      {
         "slug" : "a-shared-rtmp-account",
         "created_at" : "2017-04-22 01:02:25",
         "network" : "rtmp",
         "name" : "A shared rtmp account",
         "settings" : {
            "http_url" : "",
            "url" : "rtmp://127.0.0.1/whasdgfasfatever",
            "name" : "A shared rtmp account"
         },
         "id" : 15,
         "updated_at" : "2017-04-22 05:42:51",
         "user_id" : 2
      }
   ]
}

GET /account/:id

Returns a single account

Example Request

 curl -XGET -H 'Authorization: Bearer 005DA1A3540565CEACCC' \
   http://example.com/api/v1/account

Example Response

{
   "account" : {
      "slug" : "jprjrdev",
      "user_id" : 1,
      "updated_at" : "2017-03-19 15:10:15",
      "shares" : [
         {
            "user" : {
               "username" : "test",
               "id" : 2
            }
         }
      ],
      "id" : 14,
      "network" : "twitch",
      "name" : "jprjrdev",
      "created_at" : "2017-03-19 15:10:15",
      "settings" : {}
   }
}

POST /account/:id

Updates an account. The only allowed keys are settings (which corresponds to the settings key from an account object), ffmpeg_args, and shares. Returns the updated account

Example Request

 curl -XPOST -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer 005DA1A3540565CEACCC' \
   -d 'some-json (see request body below)' \
   http://example.com/api/v1/account/14

Example Request Body

{
   "ffmpeg_args" : null,
   "shares": [
     { "user": {
         "id": 2
     } }
   ]
}

Example Response

{
   "account" : {
      "slug" : "jprjrdev",
      "user_id" : 1,
      "updated_at" : "2017-03-19 15:10:15",
      "shares" : [
         {
            "user" : {
               "username" : "test",
               "id" : 2
            }
         }
      ],
      "id" : 14,
      "network" : "twitch",
      "name" : "jprjrdev",
      "created_at" : "2017-03-19 15:10:15",
      "settings" : {}
   }
}

GET /stream

Returns a list of available streams

Example Request

curl -XGET -H 'Authorization: Bearer 005DA1A3540565CEACCC' \
  http://example.com/api/v1/stream

Example Response

{
   "streams" : [
      {
         "slug" : "example-stream2",
         "live" : false,
         "title" : "hrm",
         "uuid" : "ce08bfe6-53c8-4daf-b481-f327721dfb61",
         "accounts" : [
            {
               "user_id" : 1,
               "name" : "jprjrdev",
               "id" : 14,
               "updated_at" : "2017-03-19 15:10:15",
               "metadata_fields" : [
                  {
                     "type" : "text",
                     "value" : "Just testing out some new API stuff",
                     "key" : "title",
                     "required" : true,
                     "label" : "Title"
                  },
                  {
                     "label" : "Game",
                     "required" : true,
                     "value" : "Creative",
                     "key" : "game",
                     "type" : "text"
                  }
               ],
               "created_at" : "2017-03-19 15:10:15",
               "network" : "twitch",
               "slug" : "jprjrdev",
               "settings" : {
                  "title" : "Just testing out some new API stuff",
                  "game" : "Creative"
               }
            }
         ],
         "created_at" : "2017-04-22 05:07:46",
         "description" : "updating the desc",
         "shares" : [
            {
               "created_at" : "2017-04-22 14:53:31",
               "chat_level" : 1,
               "updated_at" : "2017-04-22 14:58:04",
               "metadata_level" : 1,
               "user" : {
                  "id" : 2,
                  "username" : "test"
               }
            }
         ],
         "updated_at" : "2017-04-22 15:55:17",
         "user_id" : 1,
         "preview_required" : 1,
         "id" : 21,
         "name" : "Example Stream2"
      },
      {
         "created_at" : "2017-04-22 01:16:18",
         "user_id" : 2,
         "id" : 8,
         "name" : "this has chat shared",
         "slug" : "this-has-chat-shared",
         "live" : false,
         "updated_at" : "2017-04-22 01:18:33"
      },
      {
         "updated_at" : "2017-04-22 01:16:29",
         "user_id" : 2,
         "id" : 9,
         "preview_required" : 0,
         "name" : "this has metadata shared",
         "slug" : "this-has-metadata-shared",
         "title" : "test title",
         "live" : false,
         "accounts" : [
            {
               "updated_at" : "2017-04-22 01:06:15",
               "name" : "non-shared",
               "id" : 16,
               "user_id" : 2,
               "settings" : {},
               "slug" : "non-shared",
               "network" : "rtmp",
               "created_at" : "2017-04-22 01:06:15"
            }
         ],
         "created_at" : "2017-04-22 01:16:29",
         "description" : ""
      }
   ]
}

GET /stream/:id

Returns information on a single stream

Example Request

curl -XGET -H 'Authorization: Bearer 005DA1A3540565CEACCC' \
  http://example.com/api/v1/stream/21

Example Response

{
   "stream" : {
      "accounts" : [
         {
            "network" : "twitch",
            "updated_at" : "2017-03-19 15:10:15",
            "name" : "jprjrdev",
            "slug" : "jprjrdev",
            "user_id" : 1,
            "metadata_fields" : [
               {
                  "key" : "title",
                  "value" : "Just testing out some new API stuff",
                  "type" : "text",
                  "required" : true,
                  "label" : "Title"
               },
               {
                  "required" : true,
                  "label" : "Game",
                  "type" : "text",
                  "key" : "game",
                  "value" : "Creative"
               }
            ],
            "settings" : {
               "game" : "Creative",
               "title" : "Just testing out some new API stuff"
            },
            "created_at" : "2017-03-19 15:10:15",
            "id" : 14
         }
      ],
      "updated_at" : "2017-04-22 15:55:17",
      "uuid" : "ce08bfe6-53c8-4daf-b481-f327721dfb61",
      "shares" : [
         {
            "user" : {
               "id" : 2,
               "username" : "test"
            },
            "metadata_level" : 1,
            "created_at" : "2017-04-22 14:53:31",
            "chat_level" : 1,
            "updated_at" : "2017-04-22 14:58:04"
         }
      ],
      "name" : "Example Stream2",
      "user_id" : 1,
      "slug" : "example-stream2",
      "live" : false,
      "preview_required" : 1,
      "title" : "hrm",
      "description" : "updating the desc",
      "id" : 21,
      "created_at" : "2017-04-22 05:07:46"
   }
}

POST /stream/:id

Updates the metadata, accounts, etc for a stream. You can use the following keys:

• name (string): update the stream name
• title (string): generic stream title
• description (string): generic stream description
• preview_required (1/0):
  • 1: User must explicitly "go live"
  • 0: Stream starts pushing immediately
• ffmpeg_pull_args (string): arguments for a custom ffmpeg puller
• accounts (array): setup the accounts on this stream
  • accounts[i].id (integer): the account id
  • accounts[i].settings (object): key/value account settings
  • (see the metadata_fields object for information on available settings)
  • accounts[i].ffmpeg_args (string): custom ffmpeg args for this account

Example Request

 curl -XPOST -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer 005DA1A3540565CEACCC' \
   -d 'some-json (see request body below)' \
   http://example.com/api/v1/stream/21

Example Request Body

{
   "preview_required" : 0,
   "accounts" : [
      {
         "settings" : {
            "game" : "Creative",
            "title" : "I updated this via API"
         },
         "id" : 14
      }
   ]
}

Example Response

{
   "stream" : {
      "accounts" : [
         {
            "network" : "twitch",
            "updated_at" : "2017-03-19 15:10:15",
            "name" : "jprjrdev",
            "slug" : "jprjrdev",
            "user_id" : 1,
            "metadata_fields" : [
               {
                  "key" : "title",
                  "value" : "I updated this via API",
                  "type" : "text",
                  "required" : true,
                  "label" : "Title"
               },
               {
                  "required" : true,
                  "label" : "Game",
                  "type" : "text",
                  "key" : "game",
                  "value" : "Creative"
               }
            ],
            "settings" : {
               "game" : "Creative",
               "title" : "I updated this via API"
            },
            "created_at" : "2017-03-19 15:10:15",
            "id" : 14
         }
      ],
      "updated_at" : "2017-04-22 15:55:17",
      "uuid" : "ce08bfe6-53c8-4daf-b481-f327721dfb61",
      "shares" : [
         {
            "user" : {
               "id" : 2,
               "username" : "test"
            },
            "metadata_level" : 1,
            "created_at" : "2017-04-22 14:53:31",
            "chat_level" : 1,
            "updated_at" : "2017-04-22 14:58:04"
         }
      ],
      "name" : "Example Stream2",
      "user_id" : 1,
      "slug" : "example-stream2",
      "live" : false,
      "preview_required" : 1,
      "title" : "hrm",
      "description" : "updating the desc",
      "id" : 21,
      "created_at" : "2017-04-22 05:07:46"
   }
}

PATCH /stream/:id

Used to start stream pullers and pushers

Sending an empty PATCH request will get the current pull/push status

Example Request

 curl -XPATCH -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer 005DA1A3540565CEACCC' \
   -d 'some-json (see request body below)' \
   http://example.com/api/v1/stream/21

Example Request Body

{
   "data_pushing" : true
}

Example Response

{
   "status" : {
      "data_pulling" : false,
      "data_pushing" : true,
      "data_incoming" : true
   }
}

POST /stream/:id/msg

Used to manually inject messages into Multistreamer, so you can build chat integrations with your own methods.

The JSON posted, at a minimum, requires:

• network - the name of the chat network
• from.name - the name to display on the message
• type (can be "text" or "emote")
• text (the text of the message or emote)

Optional values:

• network_icon - an SVG icon to display
• network_icon_css - css rules to apply to the network icon
• from.picture - a URL to a profile picture
• markdown - a markdown version of your message

Example Request

 curl -XPOST -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer 005DA1A3540565CEACCC' \
   -d 'some-json (see request body below)' \
   http://example.com/api/v1/stream/21/msg

Example Request Body

{
  "network": "discord",
  "network_icon": "<svg>...</svg>",
  "network_icon_css": "background-color:#000;",
  "from": {
    "name": "Some guy",
    "picture": "https://example.com/profile.png"
  },
  "type": "text",
  "text": "Hey this is a custom message from a custom network"
}

Example Response

{
   "status" : "ok"
}