Download OpenAPI specification:Download
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.
{- "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 the active inbound stream, if one exists, and terminate the broadcast.
{- "success": true,
- "message": "context specific success message"
}
Used when there is a problem with your registration to the Owncast Directory via the YP APIs. This will reset your local registration key.
{- "success": true,
- "message": "context specific success message"
}
Return a list of currently connected clients with optional geo details.
[- {
- "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",
- "geo": {
- "countryCode": "US",
- "regionName": "California",
- "timeZone": "America/Los_Angeles"
}, - "user": {
- "id": "yklw5Imng",
- "displayName": "awesome-pizza",
- "displayColor": 42,
- "createdAt": "2021-07-08T20:21:25.303402404-07:00",
- "previousNames": "awesome-pizza,coolPerson23"
}
}
]
Return a list of currently connected clients with optional geo details.
[- {
- "id": "yklw5Imng",
- "displayName": "awesome-pizza",
- "displayColor": 42,
- "createdAt": "2019-08-24T14:15:22Z",
- "previousNames": "awesome-pizza,user42"
}
]
[- {
- "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.
[- {
- "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"
}
]
{- "instanceDetails": {
- "name": "string",
- "summary": "string",
- "logo": "string",
- "tags": [
- "string"
], - "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"
}
}
Get a list of all chat messages with no filters applied.
[- {
- "user": {
- "id": "yklw5Imng",
- "displayName": "awesome-pizza",
- "displayColor": 42,
- "createdAt": "2019-08-24T14:15:22Z",
- "previousNames": "awesome-pizza,user42"
}, - "body": "string",
- "id": "string",
- "visible": true,
- "timestamp": "2019-08-24T14:15:22Z"
}
]
Pass an array of IDs you want to change the chat visibility of.
visible | boolean Are these messages visible. |
idArray | Array of strings |
{- "visible": true,
- "idArray": [
- "string"
]
}
{- "success": true,
- "message": "context specific success message"
}
Enable or disable a single user. Disabling will also hide all the user's chat messages.
userId | string User ID to act upon. |
enabled | boolean Set the enabled state of this user. |
{- "userId": "yklw5Imng",
- "enabled": true
}
{- "success": true,
- "message": "context specific success message"
}
Set the stream key. Also used as the admin password.
string or integer or object or boolean |
{- "value": "string"
}
{- "success": true,
- "message": "context specific success message"
}
Set the custom page content using markdown.
string or integer or object or boolean |
"# Welcome to my cool server!<br><br>I _hope_ you enjoy it."
{- "success": true,
- "message": "context specific success message"
}
Set the title of the currently streaming content.
string or integer or object or boolean |
{- "value": "Streaming my favorite game, Desert Bus."
}
{- "success": true,
- "message": "context specific success message"
}
Set the name associated with your server. Often is your name, username or identity.
string or integer or object or boolean |
{- "value": "string"
}
{- "success": true,
- "message": "context specific success message"
}
Set the summary of your server's streaming content.
string or integer or object or boolean |
{- "value": "The best in Desert Bus Streaming"
}
{- "success": true,
- "message": "context specific success message"
}
Set the logo for your server. Path is relative to webroot.
string or integer or object or boolean |
{- "value": "/img/mylogo.png"
}
{- "success": true,
- "message": "context specific success message"
}
Set the path for a specific copy of ffmpeg on your system.
string or integer or object or boolean |
{- "value": "/home/owncast/ffmpeg"
}
{- "success": true,
- "message": "context specific success message"
}
Set the port the owncast web server should listen on.
string or integer or object or boolean |
{- "value": 8080
}
{- "success": true,
- "message": "context specific success message"
}
Set the port where owncast service will listen for inbound broadcasts.
string or integer or object or boolean |
{- "value": 1935
}
{- "success": true,
- "message": "context specific success message"
}
Mark if your stream can be consitered not safe for work. Used in different contexts, including the directory for filtering purposes.
string or integer or object or boolean |
{- "value": false
}
{- "success": true,
- "message": "context specific success message"
}
If set to true the server will attempt to register itself with the Owncast Directory. Off by default.
string or integer or object or boolean |
{- "value": true
}
{- "success": true,
- "message": "context specific success message"
}
Set the public url of this owncast server. Used for the directory and optional integrations.
string or integer or object or boolean |
{
}
{- "success": true,
- "message": "context specific success message"
}
Sets the latency level that determines how much video is buffered between the server and viewer. Less latency can end up with more buffering.
value | integer The latency level |
{- "value": 4
}
{- "success": true,
- "message": "context specific success message"
}
Sets the detailed configuration for all of the stream variants you support.
string or integer or object or boolean |
{- "value": [
- {
- "framerate": 30,
- "videoPassthrough": false,
- "videoBitrate": 1800,
- "cpuUsageLevel": 2,
- "audioPassthrough": true
}, - {
- "framerate": 24,
- "videoPassthrough": false,
- "videoBitrate": 1000,
- "cpuUsageLevel": 3,
- "audioPassthrough": true
}
]
}
{- "success": true,
- "message": "context specific success message"
}
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.
value | string The video codec to change to. |
{- "value": "libx264"
}
{- "success": true,
- "message": "context specific success message"
}
Sets your S3 storage provider configuration details to enable external storage.
string or integer or object or boolean |
{- "value": {
- "enabled": true,
- "accessKey": "e1ac500y7000500047156bd060",
- "secret": "H8FH8eSxM2K/S42CUg5K000Tt4WY2fI",
- "bucket": "video",
- "region": "us-west-000"
}
}
{- "success": true,
- "message": "context specific success message"
}
Save a string containing CSS to be inserted in to the web frontend page.
string or integer or object or boolean |
{- "value": "body { color: orange; background: black; }"
}
{- "success": true,
- "message": "context specific success message"
}
Get the CPU, Memory and Disk utilization levels over the collected period.
{- "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
}
]
}
Set a collection of external action URLs that are displayed in the UI.
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. |
[- {
- "url": "string",
- "title": "string",
- "description": "string",
- "icon": "string",
- "color": "string",
- "openExternally": true
}
]
Create a single webhook that acts on the requested events.
url | string The url to post the events to. |
events | Array of strings The events to be notified about. |
{- "url": "string",
- "events": [
- "string"
]
}
{- "name": "your new token",
- "token": "zG2xO-mHTFnelCp5xaIkYEFWcPhoOswOSRmFC1BkI="
}
Register a user that returns an access token for accessing chat.
displayName | string Optionally provide a display name you want to assign to this user when registering. |
{- "displayName": "string"
}
{- "id": "string",
- "accessToken": "string",
- "displayName": "string"
}
Used to get chat messages prior to connecting to the websocket.
[- {
- "user": {
- "id": "yklw5Imng",
- "displayName": "awesome-pizza",
- "displayColor": 42,
- "createdAt": "2019-08-24T14:15:22Z",
- "previousNames": "awesome-pizza,user42"
}, - "body": "string",
- "id": "string",
- "visible": true,
- "timestamp": "2019-08-24T14:15:22Z"
}
]
Set the title of the currently streaming content.
string or integer or object or boolean |
{- "value": "Streaming my favorite game, Desert Bus."
}
{- "success": true,
- "message": "context specific success message"
}
Send a chat message on behalf of a 3rd party integration, bot or service.
body | string The message text that will be sent as the user. |
{- "body": "string"
}
{- "success": true,
- "message": "sent"
}
Send a chat message on behalf of the system/server.
body | string The message text that will be sent as the system user. |
{- "body": "string"
}
{- "success": true,
- "message": "sent"
}
Send an action that took place to the chat.
body required | string The message text that will be sent as the system user. |
author | string An optional user name that performed the action. |
{- "body": "rolled a 15 on the dice",
- "author": "JohnSmith"
}
{- "success": true,
- "message": "sent"
}
Send a chat message on behalf of the system/server to a single client.
clientId required | integer <int64> Client ID (a unique numeric Id, identifying the client connection) |
body required | string The message text that will be sent to the client. |
{- "body": "What a beautiful day. I love it"
}
{- "success": true,
- "messages": "sent"
}
Create a single access token that has access to the access scopes provided.
name | string The human-readable name to give this access token. |
scopes | Array of strings |
{- "name": "string",
- "scopes": [
- "string"
]
}
{- "name": "your new token",
- "token": "zG2xO-mHTFnelCp5xaIkYEFWcPhoOswOSRmFC1BkI="
}
Delete a single access token.
token | string The token to delete |
{- "token": "string"
}
{- "success": true,
- "message": "deleted token"
}
Set a collection of external action URLs that are displayed in the UI.
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. |
[- {
- "url": "string",
- "title": "string",
- "description": "string",
- "icon": "string",
- "color": "string",
- "openExternally": true
}
]
Return a list of currently connected clients with optional geo details.
[- {
- "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",
- "geo": {
- "countryCode": "US",
- "regionName": "California",
- "timeZone": "America/Los_Angeles"
}, - "user": {
- "id": "yklw5Imng",
- "displayName": "awesome-pizza",
- "displayColor": 42,
- "createdAt": "2021-07-08T20:21:25.303402404-07:00",
- "previousNames": "awesome-pizza,coolPerson23"
}
}
]
[- {
- "user": {
- "id": "yklw5Imng",
- "displayName": "awesome-pizza",
- "displayColor": 42,
- "createdAt": "2019-08-24T14:15:22Z",
- "previousNames": "awesome-pizza,user42"
}, - "body": "string",
- "id": "string",
- "visible": true,
- "timestamp": "2019-08-24T14:15:22Z"
}
]
Pass an array of IDs you want to change the chat visibility of.
visible | boolean Are these messages visible. |
idArray | Array of strings |
{- "visible": true,
- "idArray": [
- "string"
]
}
{- "success": true,
- "message": "context specific success message"
}
{- "name": "string",
- "summary": "string",
- "logo": "string",
- "tags": [
- "string"
], - "extraPageContent": "<p>This page is <strong>super</strong> cool!",
- "version": "Owncast v0.0.3-macOS (ef3796a033b32a312ebf5b334851cbf9959e7ecb)"
}
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.
{- "lastConnectTime": "2020-10-03T21:36:22-05:00",
- "lastDisconnectTime": null,
- "online": true,
- "overallMaxViewerCount": 420,
- "sessionMaxViewerCount": 12,
- "viewerCount": 7
}
Information to be used in the Yellow Pages service, a global directory of Owncast servers.
{- "name": "string",
- "description": "string",
- "logo": "string",
- "nsfw": true,
- "tags": [
- "string"
], - "online": true,
- "viewerCount": 0,
- "overallMaxViewerCount": 0,
- "sessionMaxViewerCount": 0,
- "lastConnectTime": "2019-08-24T14:15:22Z"
}