Owncast (0.0.11)

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

UserToken

A standard user must provide a valid access token.

Security Scheme Type	API Key
Query parameter name:	accessToken

ModeratorUserToken

A moderator user must provide a valid access token.

Security Scheme Type	API Key
Query parameter name:	accessToken

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

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

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

[{"id": "yklw5Imng",
"displayName": "awesome-pizza",
"displayColor": 42,
"createdAt": "2019-08-24T14:15:22Z",
"previousNames": "awesome-pizza,user42",
"scopes": ["MODERATOR"
]
}
]

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",
"forcePathStyle": true
},
"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

[{"user": {"id": "yklw5Imng",
"displayName": "awesome-pizza",
"displayColor": 42,
"createdAt": "2019-08-24T14:15:22Z",
"previousNames": "awesome-pizza,user42",
"scopes": ["MODERATOR"
]
},
"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"
}

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

Payload

Content type

application/json

{"userId": "yklw5Imng",
"enabled": true
}

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

Enable or disable federated social features.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

value

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

Enable or disable private federation mode.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

value

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

Enable or disable Federation activity showing in chat.

Authorizations:

AdminBasicAuth

Request Body schema: application/json

value

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

Payload

Content type

application/json

{"value": "string"
}

Response samples

200

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

Payload

Content type

application/json

{"value": "string"
}

Response samples

200

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

Payload

Content type

application/json

{"value": ["guns.eagles.biz",
"freedom.us"
]
}

Response samples

200

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

Payload

Content type

application/json

{"value": "I'm still streaming, you should come visit."
}

Response samples

200

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

200

Content type

application/json

[{"iri": "https://fediverse.server/jfk-3827",
"actorIRI": "https://mastodon.cloud/users/gabektest",
"type": "FEDIVERSE_ENGAGEMENT_FOLLOW"
}
]

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

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

Payload

Content type

application/json

{"userId": "xJ84_48Ghj",
"isModerator": true
}

Response samples

200

Content type

application/json

Example

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

Get a list of chat moderator users.

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

[{"id": "yklw5Imng",
"displayName": "awesome-pizza",
"displayColor": 42,
"createdAt": "2019-08-24T14:15:22Z",
"previousNames": "awesome-pizza,user42",
"scopes": ["MODERATOR"
]
}
]

Get the followers of this instance

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

[{"link": "https://mastodon.cloud/users/gabektest",
"name": "John Smith",
"image": "http://mastodon.cloud/users/gabektest/avatar.png",
"timestamp": "2019-08-24T14:15:22Z",
"disabledAt": "2019-08-24T14:15:22Z"
}
]

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

Payload

Content type

application/json

{"actorIRI": "string"
}

Response samples

200

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

Payload

Content type

application/json

{"value": ["string"
]
}

Response samples

200

Content type

application/json

Example

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

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

Payload

Content type

application/json

{"displayName": "string"
}

Response samples

200

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

200

Content type

application/json

[{"user": {"id": "yklw5Imng",
"displayName": "awesome-pizza",
"displayColor": 42,
"createdAt": "2019-08-24T14:15:22Z",
"previousNames": "awesome-pizza,user42",
"scopes": ["MODERATOR"
]
},
"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 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

Payload

Content type

application/json

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

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

Payload

Content type

application/json

{"body": "What a beautiful day. I love it"
}

Response samples

200
500

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

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

Historical Chat Messages

Used to get the backlog of chat messages.

Authorizations:

AccessToken

Responses

Response samples

200

Content type

application/json

[{"user": {"id": "yklw5Imng",
"displayName": "awesome-pizza",
"displayColor": 42,
"createdAt": "2019-08-24T14:15:22Z",
"previousNames": "awesome-pizza,user42",
"scopes": ["MODERATOR"
]
},
"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"
}

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

Payload

Content type

application/json

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

Response samples

200

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

Payload

Content type

application/json

{"userId": "string",
"enabled": true
}

Response samples

200

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

Payload

Content type

application/json

{"userId": "xJ84_48Ghj",
"isModerator": true
}

Response samples

200

Content type

application/json

Example

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

Get a list of chat moderator users.

Authorizations:

AdminBasicAuth

Responses

Response samples

200

Content type

application/json

[{"id": "yklw5Imng",
"displayName": "awesome-pizza",
"displayColor": 42,
"createdAt": "2019-08-24T14:15:22Z",
"previousNames": "awesome-pizza,user42",
"scopes": ["MODERATOR"
]
}
]

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

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

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

Get the public followers of this instance

Responses

Response samples

200

Content type

application/json

[{"link": "https://mastodon.cloud/users/gabektest",
"name": "John Smith",
"image": "http://mastodon.cloud/users/gabektest/avatar.png",
"timestamp": "2019-08-24T14:15:22Z",
"disabledAt": "2019-08-24T14:15:22Z"
}
]

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

Payload

Content type

application/json

{"account": "johnsmith@fediverse.biz"
}

Response samples

200

Content type

application/json

{"redirectUrl": "https://fediverse.biz/authorize_interaction?uri=https://my.owncast.server/federation/user/streamer"
}