Owncast (0.0.7)

Download OpenAPI specification:Download

Gabe Kangas: gabek@real-ity.com URL: http://owncast.online

Owncast is a self-hosted live video and web chat server for use with existing popular broadcasting software. The following APIs represent the state in the development branch.

Authentication

AdminBasicAuth

The username for admin basic auth is admin and the password is the stream key.

Security Scheme Type	HTTP
HTTP Authorization Scheme	basic

AccessToken

3rd party integration auth where a service user must provide an access token.

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer

Admin

Admin operations requiring authentication.

Server status and broadcaster

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

{"broadcaster": {"remoteAddr": "172.217.164.110",
"time": "2020-10-06T23:20:44.588649-07:00",
"streamDetails": {"width": 640,
"height": 480,
"frameRate": 24,
"videoBitrate": 1500,
"videoCodec": "mp4a",
"audioBitrate": 256,
"audioCodec": "aac",
"encoder": "obs-output module (libobs version 25.0.8)"
}
},
"online": true,
"viewerCount": 3,
"overallPeakViewerCount": 4,
"sessionPeakViewerCount": 4,
"versionNumber": "0.0.3"
}

Disconnect Broadcaster

Disconnect the active inbound stream, if one exists, and terminate the broadcast.

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Reset your YP registration key.

Used when there is a problem with your registration to the Owncast Directory via the YP APIs. This will reset your local registration key.

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Return a list of currently connected clients

Return a list of currently connected clients with optional geo details.

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

[{"connectedAt": "2020-10-06T23:20:44.588649-07:00",
"messageCount": 3,
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.89 Safari/537.36",
"ipAddress": "172.217.164.110",
"username": "coolperson42",
"clientID": "2ba20dd34f911c198df3218ddc64c740",
"geo": {"countryCode": "US",
"regionName": "California",
"timeZone": "America/Los_Angeles"
}
}
]

Return recent log entries

Returns server logs.

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

[{"message": "Owncast v0.0.0-localdev (unknown)",
"level": "info",
"time": "2020-10-29T18:35:34.422386-07:00"
},
{"message": "Web server running on port: 8080",
"level": "info",
"time": "2020-10-29T18:35:35.011731-07:00"
},
{"message": "RTMP server is listening for incoming stream on port: 1935",
"level": "info",
"time": "2020-10-29T18:35:35.011823-07:00"
}
]

Return recent warning and error logs.

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

[{"message": "Owncast v0.0.0-localdev (unknown)",
"level": "info",
"time": "2020-10-29T18:35:34.422386-07:00"
},
{"message": "Web server running on port: 8080",
"level": "info",
"time": "2020-10-29T18:35:35.011731-07:00"
},
{"message": "RTMP server is listening for incoming stream on port: 1935",
"level": "info",
"time": "2020-10-29T18:35:35.011823-07:00"
}
]

Server Configuration

Get the current configuration of the Owncast server.

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

{"instanceDetails": {"name": "string",
"summary": "string",
"logo": "string",
"tags": ["string"
],
"socialHandles": [{"platform": "github",
"url": "http://github.com/owncast/owncast"
}
],
"extraPageContent": "<p>This page is <strong>super</strong> cool!",
"version": "Owncast v0.0.3-macOS (ef3796a033b32a312ebf5b334851cbf9959e7ecb)"
},
"ffmpegPath": "string",
"webServerPort": 0,
"rtmpServerPort": 0,
"s3": {"enabled": true,
"endpoint": "string",
"servingEndpoint": "string",
"accessKey": "string",
"secret": "string",
"bucket": "string",
"region": "string",
"acl": "string"
},
"videoSettings": {"videoQualityVariants": [{"videoPassthrough": true,
"audioPassthrough": true,
"videoBitrate": 0,
"audioBitrate": 0,
"scaledWidth": 0,
"scaledHeight": 0,
"framerate": 0,
"cpuUsageLevel": 0
}
],
"latencyLevel": 0
},
"yp": {"enabled": false,
"instanceUrl": "string"
}
}

Chat messages, unfiltered.

Get a list of all chat messages with no filters applied.

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

[{"author": "string",
"body": "string",
"id": "string",
"visible": true,
"timestamp": "2019-08-24T14:15:22Z"
}
]

Update the visibility of chat messages.

Pass an array of IDs you want to change the chat visibility of.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

visible	boolean Are these messages visible.
idArray	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"visible": true,
"idArray": ["string"
]
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set the stream key.

Set the stream key. Also used as the admin password.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": "string"
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set the custom page content.

Set the custom page content using markdown.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

"# Welcome to my cool server!<br><br>I _hope_ you enjoy it."

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set the stream title.

Set the title of the currently streaming content.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": "Streaming my favorite game, Desert Bus."
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set the server name.

Set the name associated with your server. Often is your name, username or identity.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": "string"
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set the server summary.

Set the summary of your server's streaming content.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": "The best in Desert Bus Streaming"
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set the server logo.

Set the logo for your server. Path is relative to webroot.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": "/img/mylogo.png"
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set the server tags.

Set the tags displayed for your server and the categories you can show up in on the directory.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": ["games",
"music",
"streaming"
]
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set the ffmpeg binary path

Set the path for a specific copy of ffmpeg on your system.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": "/home/owncast/ffmpeg"
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set the owncast web port.

Set the port the owncast web server should listen on.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": 8080
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set the inbound rtmp server port.

Set the port where owncast service will listen for inbound broadcasts.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": 1935
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Mark if your stream is not safe for work

Mark if your stream can be consitered not safe for work. Used in different contexts, including the directory for filtering purposes.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": false
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set if this server supports the Owncast directory.

If set to true the server will attempt to register itself with the Owncast Directory. Off by default.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": true
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set the public url of this owncast server.

Set the public url of this owncast server. Used for the directory and optional integrations.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": "https://live.mycoolserver.biz"
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set the latency level for the stream.

Sets the latency level that determines how much video is buffered between the server and viewer. Less latency can end up with more buffering.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

value

integer

The latency level

Responses

Request samples

Payload

Content type

application/json

{"value": 4
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set the configuration of your stream output.

Sets the detailed configuration for all of the stream variants you support.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": [{"framerate": 30,
"videoPassthrough": false,
"videoBitrate": 1800,
"cpuUsageLevel": 2,
"audioPassthrough": true
},
{"framerate": 24,
"videoPassthrough": false,
"videoBitrate": 1000,
"cpuUsageLevel": 3,
"audioPassthrough": true
}
]
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set the video codec.

Sets the specific video codec that will be used for video encoding. Some codecs will support hardware acceleration. Not all codecs will be supported for all systems.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

value

string

The video codec to change to.

Responses

Request samples

Payload

Content type

application/json

{"value": "libx264"
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set your storage configration.

Sets your S3 storage provider configuration details to enable external storage.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": {"enabled": true,
"endpoint": "https://s3.us-west-000.backblazeb2.com",
"accessKey": "e1ac500y7000500047156bd060",
"secret": "H8FH8eSxM2K/S42CUg5K000Tt4WY2fI",
"bucket": "video",
"region": "us-west-000"
}
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Set your social handles.

Sets the external links to social networks and profiles.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": [{"platform": "github",
"url": "https://github.com/owncast/owncast"
},
{"platform": "mastodon",
"url": "https://mastodon.social/@gabek"
}
]
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Custom CSS styles to be used in the web front endpoints.

Save a string containing CSS to be inserted in to the web frontend page.

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": "body { color: orange; background: black; }"
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Viewers Over Time

Get the tracked viewer count over the collected period.

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

[{"time": "2020-10-03T21:41:00.381996-05:00",
"value": 50
},
{"time": "2020-10-03T21:42:00.381996-05:00",
"value": 52
}
]

Hardware Stats

Get the CPU, Memory and Disk utilization levels over the collected period.

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

{"cpu": [{"time": "2020-10-03T21:41:00.381996-05:00",
"value": 23
},
{"time": "2020-10-03T21:42:00.381996-05:00",
"value": 27
},
{"time": "2020-10-03T21:43:00.381996-05:00",
"value": 22
}
],
"memory": [{"time": "2020-10-03T21:41:00.381996-05:00",
"value": 65
},
{"time": "2020-10-03T21:42:00.381996-05:00",
"value": 66
},
{"time": "2020-10-03T21:43:00.381996-05:00",
"value": 72
}
],
"disk": [{"time": "2020-10-03T21:41:00.381996-05:00",
"value": 11
},
{"time": "2020-10-03T21:42:00.381996-05:00",
"value": 11
},
{"time": "2020-10-03T21:43:00.381996-05:00",
"value": 11
}
]
}

Return all webhooks.

Return all of the configured webhooks for external events.

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

{"id": "string",
"url": "string",
"events": ["string"
],
"timestamp": "2019-08-24T14:15:22Z",
"lastUsed": "2019-08-24T14:15:22Z"
}

Set external action URLs.

Set a collection of external action URLs that are displayed in the UI.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

Array ()

url	string URL of the external action content.
title	string The title to put on the external action button.
description	string Optional additional description to display in the UI.
icon	string The URL to an image to place on the external action button.
color	string Optional color to use for drawing the action button.
openExternally	boolean If set this action will open in a new browser tab instead of an internal modal.

Responses

Request samples

Payload

Content type

application/json

[{"url": "string",
"title": "string",
"description": "string",
"icon": "string",
"color": "string",
"openExternally": true
}
]

Delete a single webhook.

Delete a single webhook by its ID.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

id	string The webhook id to delete

Responses

Request samples

Payload

Content type

application/json

{"id": "string"
}

Create a webhook.

Create a single webhook that acts on the requested events.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

url	string The url to post the events to.
events	Array of strings The events to be notified about.

Responses

Request samples

Payload

Content type

application/json

{"url": "string",
"events": ["string"
]
}

Response samples

200

Content type

application/json

{"name": "your new token",
"token": "zG2xO-mHTFnelCp5xaIkYEFWcPhoOswOSRmFC1BkI="
}

Chat

Endpoints related to the chat interface.

Historical Chat Messages

Used to get all chat messages prior to connecting to the websocket.

Responses

Response samples

200

Content type

application/json

[{"author": "string",
"body": "string",
"id": "string",
"visible": true,
"timestamp": "2019-08-24T14:15:22Z"
}
]

Get Custom Emoji

Get a list of custom emoji that are supported in chat.

Responses

Response samples

200

Content type

application/json

{"items": [{"name": "nicolas_cage_party",
"emoji": "/img/emoji/nicolas_cage_party.gif"
},
{"name": "parrot",
"emoji": "/img/emoji/parrot.gif"
}
]
}

Integrations

APIs built to allow 3rd parties to interact with an Owncast server.

Set the stream title.

Set the title of the currently streaming content.

Authorizations:

AccessToken

Request Body schema: application/json

string or integer or object or boolean

Responses

Request samples

Payload

Content type

application/json

{"value": "Streaming my favorite game, Desert Bus."
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Send a user chat message.

Send a chat message on behalf of a user. Could be a bot name or a real user.

Authorizations:

AccessToken

Request Body schema: application/json

user	string The user you want to send this message as.
body	string The message text that will be sent as the user.

Responses

Request samples

Payload

Content type

application/json

{"user": "string",
"body": "string"
}

Response samples

200

Content type

application/json

{"success": true,
"message": "sent"
}

Send a system chat message.

Send a chat message on behalf of the system/server.

Authorizations:

AccessToken

Request Body schema: application/json

body	string The message text that will be sent as the system user.

Responses

Request samples

Payload

Content type

application/json

{"body": "string"
}

Response samples

200

Content type

application/json

{"success": true,
"message": "sent"
}

Send a chat action.

Send an action that took place to the chat.

Authorizations:

AccessToken

Request Body schema: application/json

body required	string The message text that will be sent as the system user.
author	string An optional user name that performed the action.

Responses

Request samples

Payload

Content type

application/json

{"body": "rolled a 15 on the dice",
"author": "JohnSmith"
}

Response samples

200

Content type

application/json

{"success": true,
"message": "sent"
}

Create an access token.

Create a single access token that has access to the access scopes provided.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

name	string The human-readable name to give this access token.
scopes	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"scopes": ["string"
]
}

Response samples

200

Content type

application/json

{"name": "your new token",
"token": "zG2xO-mHTFnelCp5xaIkYEFWcPhoOswOSRmFC1BkI="
}

Delete an access token.

Delete a single access token.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

token

string

The token to delete

Responses

Request samples

Payload

Content type

application/json

{"token": "string"
}

Response samples

200

Content type

application/json

{"success": true,
"message": "deleted token"
}

Return all access tokens.

Return all of the available access tokens.

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

["string"
]

Set external action URLs.

Set a collection of external action URLs that are displayed in the UI.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

Array ()

url	string URL of the external action content.
title	string The title to put on the external action button.
description	string Optional additional description to display in the UI.
icon	string The URL to an image to place on the external action button.
color	string Optional color to use for drawing the action button.
openExternally	boolean If set this action will open in a new browser tab instead of an internal modal.

Responses

Request samples

Payload

Content type

application/json

[{"url": "string",
"title": "string",
"description": "string",
"icon": "string",
"color": "string",
"openExternally": true
}
]

Return a list of currently connected clients

Return a list of currently connected clients with optional geo details.

Authorizations:

AccessToken

Responses

Response samples

200

Content type

application/json

[{"connectedAt": "2020-10-06T23:20:44.588649-07:00",
"messageCount": 3,
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.89 Safari/537.36",
"ipAddress": "172.217.164.110",
"username": "coolperson42",
"clientID": "2ba20dd34f911c198df3218ddc64c740",
"geo": {"countryCode": "US",
"regionName": "California",
"timeZone": "America/Los_Angeles"
}
}
]

Historical Chat Messages

Used to get the backlog of chat messages.

Authorizations:

AccessToken

Responses

Response samples

200

Content type

application/json

[{"author": "string",
"body": "string",
"id": "string",
"visible": true,
"timestamp": "2019-08-24T14:15:22Z"
}
]

Update the visibility of chat messages.

Pass an array of IDs you want to change the chat visibility of.

Authorizations:

AccessToken

Request Body schema: application/json

visible	boolean Are these messages visible.
idArray	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"visible": true,
"idArray": ["string"
]
}

Response samples

200

Content type

application/json

Example

{"success": true,
"message": "context specific success message"
}

Server

Information

The client configuration. Information useful for the user interface.

Responses

Response samples

200

Content type

application/json

{"name": "string",
"summary": "string",
"logo": "string",
"tags": ["string"
],
"socialHandles": [{"platform": "github",
"url": "http://github.com/owncast/owncast"
}
],
"extraPageContent": "<p>This page is <strong>super</strong> cool!",
"version": "Owncast v0.0.3-macOS (ef3796a033b32a312ebf5b334851cbf9959e7ecb)"
}

Current Status

This endpoint is used to discover when a server is broadcasting, the number of active viewers as well as other useful information for updating the user interface.

Responses

Response samples

200

Content type

application/json

{"lastConnectTime": "2020-10-03T21:36:22-05:00",
"lastDisconnectTime": null,
"online": true,
"overallMaxViewerCount": 420,
"sessionMaxViewerCount": 12,
"viewerCount": 7
}

Yellow Pages Information

Information to be used in the Yellow Pages service, a global directory of Owncast servers.

Responses

Response samples

200

Content type

application/json

{"name": "string",
"description": "string",
"logo": "string",
"nsfw": true,
"tags": ["string"
],
"online": true,
"viewerCount": 0,
"overallMaxViewerCount": 0,
"sessionMaxViewerCount": 0,
"lastConnectTime": "2019-08-24T14:15:22Z"
}