Owncast (0.0.5-development)

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 master 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

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",
"disableUpgradeChecks": false
}

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"
}

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"
}
]

Update Stream Key. Pre-release, do not use.

Change the stream key in memory, but not in the config file. This will require all broadcasters to be reconfigured to connect again.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

key

string

Responses

Request samples

Payload

Content type

application/json

{"key": "string"
}

Response samples

200

Content type

application/json

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

Change the extra page content. Pre-release, do not use.

Change the extra page content in memory, but not on disk.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

content

string

Responses

Request samples

Payload

Content type

application/json

{"content": "string"
}

Response samples

200

Content type

application/json

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

Update Stream Title. Pre-release, do not use.

Change the stream title in memory, but not in the config file.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

title

string

Responses

Request samples

Payload

Content type

application/json

{"title": "string"
}

Response samples

200

Content type

application/json

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

Update Stream Name. Pre-release, do not use.

Change the stream name in memory, but not in the config file.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

name

string

Responses

Request samples

Payload

Content type

application/json

{"name": "string"
}

Response samples

200

Content type

application/json

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

Update Stream Tags. Pre-release, do not use.

Change the stream tags in memory, but not in the config file.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

tags	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"tags": ["string"
]
}

Response samples

200

Content type

application/json

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

Server Configuration

Get the current configuration of the Owncast server.

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

{"instanceDetails": {"name": "string",
"title": "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,
"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,
"encoderPreset": "string"
}
],
"segmentLengthSeconds": 0,
"numberOfPlaylistItems": 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 in "Get the CPU, Memory and Disk utilization levels over the collected period."
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"
}

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
}
]
}

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"
}
]
}

Server

Information

The client configuration. Information useful for the user interface.

Responses

Response samples

200

Content type

application/json

{"name": "string",
"title": "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"
}

Pre-release

Update Stream Key. Pre-release, do not use.

Change the stream key in memory, but not in the config file. This will require all broadcasters to be reconfigured to connect again.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

key

string

Responses

Request samples

Payload

Content type

application/json

{"key": "string"
}

Response samples

200

Content type

application/json

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

Change the extra page content. Pre-release, do not use.

Change the extra page content in memory, but not on disk.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

content

string

Responses

Request samples

Payload

Content type

application/json

{"content": "string"
}

Response samples

200

Content type

application/json

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

Update Stream Title. Pre-release, do not use.

Change the stream title in memory, but not in the config file.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

title

string

Responses

Request samples

Payload

Content type

application/json

{"title": "string"
}

Response samples

200

Content type

application/json

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

Update Stream Name. Pre-release, do not use.

Change the stream name in memory, but not in the config file.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

name

string

Responses

Request samples

Payload

Content type

application/json

{"name": "string"
}

Response samples

200

Content type

application/json

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

Update Stream Tags. Pre-release, do not use.

Change the stream tags in memory, but not in the config file.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

tags	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"tags": ["string"
]
}

Response samples

200

Content type

application/json

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