logo
Documentation Powered by Redocly

Owncast (0.0.12)

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.

Admin

Admin operations requiring authentication.

Server status and broadcaster

Authorizations:
AdminBasicAuth

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

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

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

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Return recent log entries

Returns server logs.

Authorizations:
AdminBasicAuth

Responses

Response samples

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

Return recent warning and error logs.

Return recent warning and error logs.

Authorizations:
AdminBasicAuth

Responses

Response samples

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

Server Configuration

Get the current configuration of the Owncast server.

Authorizations:
AdminBasicAuth

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

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

Responses

Response samples

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

Hardware Stats

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

Authorizations:
AdminBasicAuth

Responses

Response samples

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

Enable or disable federated social features.

Authorizations:
AdminBasicAuth
Request Body schema: application/json
value
boolean

Responses

Request samples

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

Response samples

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

Enable or disable private federation mode.

Authorizations:
AdminBasicAuth
Request Body schema: application/json
value
boolean

Responses

Request samples

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

Response samples

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

Enable or disable Federation activity showing in chat.

Authorizations:
AdminBasicAuth
Request Body schema: application/json
value
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 username you are seen as on the fediverse.

Authorizations:
AdminBasicAuth
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 message sent to the fediverse when this instance goes live.

Authorizations:
AdminBasicAuth
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"
}

Save a collection of domains that should be ignored on the fediverse.

Authorizations:
AdminBasicAuth
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"
}

Manually send a message to the fediverse from this instance.

Authorizations:
AdminBasicAuth
Request Body schema: application/json
string or integer or object or boolean

Responses

Request samples

Content type
application/json
{
  • "value": "I'm still streaming, you should come visit."
}

Response samples

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

Get a list of accepted actions that took place on the Fediverse.

Authorizations:
AdminBasicAuth

Responses

Response samples

Content type
application/json
[]

Return all webhooks.

Return all of the configured webhooks for external events.

Authorizations:
AdminBasicAuth

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

Content type
application/json
[
  • {
    }
]

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

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

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

Response samples

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

Set moderator priviledges on a chat users.

Give a chat user ID and be able to grant or remove moderator priviledges to this user.

Authorizations:
AdminBasicAuth
Request Body schema: application/json
userId
string

User ID of the chat user you want to change moderation status of.

isModerator
boolean

The moderator status of this user.

Responses

Request samples

Content type
application/json
{
  • "userId": "xJ84_48Ghj",
  • "isModerator": true
}

Response samples

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

Get a list of chat moderator users.

Authorizations:
AdminBasicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the followers of this instance

Authorizations:
AdminBasicAuth

Responses

Response samples

Content type
application/json
[]

Get a list of follow requests that are pending.

Authorizations:
AdminBasicAuth

Responses

Get a list of follow requests that have been blocked/rejected.

Authorizations:
AdminBasicAuth

Responses

Approve a pending follow request.

Authorizations:
AdminBasicAuth
Request Body schema: application/json
actorIRI
string

The requestor's remote IRI used to identify the user.

Responses

Request samples

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

Response samples

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

A list of names to select from randomly for new chat users.

Authorizations:
AdminBasicAuth
Request Body schema: application/json
value
Array of strings

Responses

Request samples

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

Response samples

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

Return Prometheus-compatible scraper metrics.

Authorizations:
AdminBasicAuth

Responses

Chat

Endpoints related to the chat interface.

Register a chat user

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

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

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

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:
AccessToken
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:
AdminBasicAuth
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:
AdminBasicAuth
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:
AdminBasicAuth

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

Content type
application/json
[
  • {
    }
]

Return a list of currently connected clients

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

Authorizations:
AccessToken

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Historical Chat Messages

Used to get the backlog of chat messages.

Authorizations:
AccessToken

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

Moderation

Chat-related actions that can take place by a moderator.

Update the visibility of chat messages.

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

Authorizations:
ModeratorUserToken
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"
}

Disable (block) or re-enable a chat user.

Authorizations:
ModeratorUserToken
Request Body schema: application/json
userId
string

User ID of the chat user you're changing.

enabled
boolean

State of this user. False to block/disable.

Responses

Request samples

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

Response samples

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

Set moderator priviledges on a chat users.

Give a chat user ID and be able to grant or remove moderator priviledges to this user.

Authorizations:
AdminBasicAuth
Request Body schema: application/json
userId
string

User ID of the chat user you want to change moderation status of.

isModerator
boolean

The moderator status of this user.

Responses

Request samples

Content type
application/json
{
  • "userId": "xJ84_48Ghj",
  • "isModerator": true
}

Response samples

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

Get a list of chat moderator users.

Authorizations:
AdminBasicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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

Get the public followers of this instance

Responses

Response samples

Content type
application/json
[]

Return the information needed to redirect a user to a fediverse server to perform a remote follow action.

Request Body schema: application/json
account
string

The fediverse username@server.tld account that wants to perform the remote follow action.

Responses

Request samples

Content type
application/json
{
  • "account": "johnsmith@fediverse.biz"
}

Response samples