Owncast (0.0.10-dev)

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.

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

UserToken

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

Security Scheme Type API Key
Query parameter name: accessToken

Admin

Admin operations requiring authentication.

Server status and broadcaster

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "broadcaster": {
    },
  • "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:

Responses

Response samples

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:

Responses

Response samples

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:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Return a list of currently connected clients

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

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Return recent log entries

Returns server logs.

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Return recent warning and error logs.

Return recent warning and error logs.

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Server Configuration

Get the current configuration of the Owncast server.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "instanceDetails": {
    },
  • "ffmpegPath": "string",
  • "webServerPort": 0,
  • "rtmpServerPort": 0,
  • "s3": {
    },
  • "videoSettings": {
    },
  • "yp": {
    }
}

Chat messages, unfiltered.

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

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update the visibility of chat messages.

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

Authorizations:
Request Body schema: application/json
visible
boolean

Are these messages visible.

idArray
Array of strings

Responses

Request samples

Content type
application/json
{
  • "visible": true,
  • "idArray": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "context specific success message"
}

Enable or disable a single user.

Enable or disable a single user. Disabling will also hide all the user's chat messages.

Authorizations:
Request Body schema: application/json
userId
string

User ID to act upon.

enabled
boolean

Set the enabled state of this user.

Responses

Request samples

Content type
application/json
{
  • "userId": "yklw5Imng",
  • "enabled": true
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": "string"
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
"# Welcome to my cool server!<br><br>I _hope_ you enjoy it."

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": "Streaming my favorite game, Desert Bus."
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": "string"
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": "The best in Desert Bus Streaming"
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": "/img/mylogo.png"
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": [
    ]
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": "/home/owncast/ffmpeg"
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": 8080
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": 1935
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": false
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": true
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json

Response samples

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:
Request Body schema: application/json
value
integer

The latency level

Responses

Request samples

Content type
application/json
{
  • "value": 4
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": [
    ]
}

Response samples

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:
Request Body schema: application/json
value
string

The video codec to change to.

Responses

Request samples

Content type
application/json
{
  • "value": "libx264"
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": {
    }
}

Response samples

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{}

Response samples

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

Content type
application/json
{
  • "value": "body { color: orange; background: black; }"
}

Response samples

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:

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Hardware Stats

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

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "cpu": [
    ],
  • "memory": [
    ],
  • "disk": [
    ]
}

Return all webhooks.

Return all of the configured webhooks for external events.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "events": [
    ],
  • "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:
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

Content type
application/json
[
  • {
    }
]

Delete a single webhook.

Delete a single webhook by its ID.

Authorizations:
Request Body schema: application/json
id
string

The webhook id to delete

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Create a webhook.

Create a single webhook that acts on the requested events.

Authorizations:
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

Content type
application/json
{
  • "url": "string",
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "your new token",
  • "token": "zG2xO-mHTFnelCp5xaIkYEFWcPhoOswOSRmFC1BkI="
}

Chat

Endpoints related to the chat interface.

Register a chat user

Register a user that returns an access token for accessing chat.

Authorizations:
Request Body schema: application/json
displayName
string

Optionally provide a display name you want to assign to this user when registering.

Responses

Request samples

Content type
application/json
{
  • "displayName": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "accessToken": "string",
  • "displayName": "string"
}

Chat Messages Backlog

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

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Custom Emoji

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

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

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:
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": "Streaming my favorite game, Desert Bus."
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "context specific success message"
}

Send a chat message.

Send a chat message on behalf of a 3rd party integration, bot or service.

Authorizations:
Request Body schema: application/json
body
string

The message text that will be sent as the user.

Responses

Request samples

Content type
application/json
{
  • "body": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "sent"
}

Send a system chat message.

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

Authorizations:
Request Body schema: application/json
body
string

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

Responses

Request samples

Content type
application/json
{
  • "body": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "sent"
}

Send a chat action.

Send an action that took place to the chat.

Authorizations:
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

Content type
application/json
{
  • "body": "rolled a 15 on the dice",
  • "author": "JohnSmith"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "sent"
}

Send system chat message to a client, identified by its ClientId

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

Authorizations:
path Parameters
clientId
required
integer <int64>

Client ID (a unique numeric Id, identifying the client connection)

Request Body schema: application/json
body
required
string

The message text that will be sent to the client.

Responses

Request samples

Content type
application/json
{
  • "body": "What a beautiful day. I love it"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "messages": "sent"
}

Create an access token.

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

Authorizations:
Request Body schema: application/json
name
string

The human-readable name to give this access token.

scopes
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "your new token",
  • "token": "zG2xO-mHTFnelCp5xaIkYEFWcPhoOswOSRmFC1BkI="
}

Delete an access token.

Delete a single access token.

Authorizations:
Request Body schema: application/json
token
string

The token to delete

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "deleted token"
}

Return all access tokens.

Return all of the available access tokens.

Authorizations:

Responses

Response samples

Content type
application/json
[
  • "string"
]

Set external action URLs.

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

Authorizations:
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

Content type
application/json
[
  • {
    }
]

Return a list of currently connected clients

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

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Historical Chat Messages

Used to get the backlog of chat messages.

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update the visibility of chat messages.

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

Authorizations:
Request Body schema: application/json
visible
boolean

Are these messages visible.

idArray
Array of strings

Responses

Request samples

Content type
application/json
{
  • "visible": true,
  • "idArray": [
    ]
}

Response samples

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

Content type
application/json
{
  • "name": "string",
  • "summary": "string",
  • "logo": "string",
  • "tags": [
    ],
  • "socialHandles": [],
  • "extraPageContent": "<p>This page is <strong>super</strong> cool!",
  • "version": "Owncast v0.0.3-macOS (ef3796a033b32a312ebf5b334851cbf9959e7ecb)"
}

Mark the current viewer as active.

For tracking viewer count, periodically hit the ping endpoint.

Responses

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

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

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