This page is super cool!'
version:
type: string
example: Owncast v0.0.3-macOS (ef3796a033b32a312ebf5b334851cbf9959e7ecb)
YP:
type: object
description: Configuration of the instance's registration to the Owncast Directory (YP API)
properties:
enabled:
type: boolean
description: If YP support is on or off. Must be enabled to show in the directory.
default: false
instanceUrl:
type: string
description: The public URL of this owncast server, used for registration and linking with the directory. Must be publicly available.
S3:
type: object
description: Configuration of external storage using S3-compatible providers.
properties:
enabled:
type: boolean
endpoint:
type: string
servingEndpoint:
type: string
accessKey:
type: string
secret:
type: string
bucket:
type: string
region:
type: string
acl:
type: string
forcePathStyle:
type: boolean
required:
- enabled
StreamQuality:
type: object
properties:
videoPassthrough:
type: boolean
description: If enabled video transcoding is disabled and the video is passed along in its original format.
audioPassthrough:
type: boolean
description: If enabled audio transcoding is disabled and the audio is passed along in its original format.
videoBitrate:
type: integer
description: The video quality, in kbps.
audioBitrate:
type: integer
description: The audio quality, in kbps.
scaledWidth:
type: integer
description: The resized video width.
scaledHeight:
type: integer
description: The resized video height.
framerate:
type: integer
description: The target frames per second of the video.
cpuUsageLevel:
type: integer
description: 'The amount of hardware utilization selected for this HLS variant.'
TimestampedValue:
type: object
properties:
time:
type: string
format: date-time
value:
type: integer
ConfigValue:
description: A wrapper object used to set values in many config endpoints.
type: object
properties:
value:
oneOf:
- type: string
- type: integer
- type: object
- type: boolean
BooleanValue:
description: A wrapper object used to set boolean values in many config endpoints.
type: object
properties:
value:
type: boolean
example:
value: true
LogEntry:
type: object
properties:
time:
type: string
format: date-time
description: 'Timestamp for this log entry'
level:
type: string
description: 'The level of this log entry'
message:
type: string
description: 'The log entry contents'
Webhook:
type: object
properties:
id:
type: string
description: The ID of this webhook.
url:
type: string
description: The URL that events will be sent to.
events:
type: array
items:
type: string
description: The events that will be sent to this webhook.
timestamp:
type: string
format: date-time
description: When this webhook was created.
lastUsed:
type: string
format: date-time
description: When this webhook was last used.
User:
type: object
properties:
id:
type: string
description: User ID
example: yklw5Imng
displayName:
type: string
description: The user-facing disaplay name for this user.
example: awesome-pizza
displayColor:
type: integer
description: Color name number for client rendering. theme-user-colors-n
example: 3
createdAt:
type: string
format: date-time
description: When this account was originally registered/created.
previousNames:
type: string
description: Comma separated list of names previously used by this user.
example: 'awesome-pizza,user42'
scopes:
type: array
items:
description: A specific attribute assigned to this user
type: string
example: 'MODERATOR'
Follower:
type: object
required:
- link
- username
- timestamp
properties:
link:
type: string
description: URL linking to this follower
example: https://mastodon.cloud/users/gabektest
name:
type: string
description: Optional display name for this follower
example: John Smith
image:
type: string
description: Optional image for this follower
example: http://mastodon.cloud/users/gabektest/avatar.png
timestamp:
type: string
format: date-time
description: Timestamp of when the follow occurred
disabledAt:
type: string
format: date-time
description: Timestamp when the follow was removed
FederatedAction:
type: object
properties:
iri:
type: string
description: The unique identifier for this action.
example: https://fediverse.server/jfk-3827
actorIRI:
type: string
description: The identifier for the actor that performed this action.
example: https://mastodon.cloud/users/gabektest
type:
type: string
enum:
[
FEDIVERSE_ENGAGEMENT_FOLLOW,
FEDIVERSE_ENGAGEMENT_LIKE,
FEDIVERSE_ENGAGEMENT_REPOST,
]
StreamKey:
type: object
properties:
id:
type: string
description: The key used for authing a stream.
example: yklw5Imng
comment:
type: string
description: The user-facing description or explanation of this single key
example: Used by Tim.
ChatMessage:
type: array
items:
type: object
properties:
user:
$ref: '#/components/schemas/User'
body:
type: string
description: Escaped HTML of the chat message content.
id:
type: string
description: Unique ID of the chat message.
visible:
type: boolean
description: 'Should chat message be visibly rendered.'
timestamp:
type: string
format: date-time
securitySchemes:
AdminBasicAuth:
type: http
scheme: basic
description: The username for admin basic auth is `admin`. Defaults to abc123.
AccessToken:
type: http
scheme: bearer
description: 3rd party integration auth where a service user must provide an access token.
UserToken:
type: apiKey
name: accessToken
in: query
description: A standard user must provide a valid access token.
ModeratorUserToken:
type: apiKey
name: accessToken
in: query
description: A moderator user must provide a valid access token.
responses:
UsersResponse:
description: A collection of users.
content:
application/json:
schema:
$ref: '#/components/schemas/UserArray'
FollowersResponse:
description: A collection of users.
content:
application/json:
schema:
$ref: '#/components/schemas/FollowerArray'
ClientsResponse:
description: Successful response of an array of clients
content:
application/json:
schema:
$ref: '#/components/schemas/ClientArray'
example:
- 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'
LogsResponse:
description: Response of server log entries
content:
application/json:
schema:
$ref: '#/components/schemas/LogEntryArray'
examples:
success:
summary: Logs returned
value:
[
{
'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',
},
]
BasicResponse:
description: Operation Success/Failure Response
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponse'
examples:
success:
summary: Operation succeeded.
value:
{
'success': true,
'message': 'context specific success message',
}
failure:
summary: Operation failed.
value:
{
'success': false,
'message': 'context specific failure message',
}
paths:
/api/config:
get:
summary: Information
description: The client configuration. Information useful for the user interface.
tags: ['Server']
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceDetails'
/api/ping:
get:
summary: Mark the current viewer as active.
description: For tracking viewer count, periodically hit the ping endpoint.
tags: ['Server']
responses:
'200':
description: 'Successful ping'
/api/status:
get:
summary: Current Status
description: 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.
tags: ['Server']
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
lastConnectTime:
type: string
nullable: true
format: date-time
overallMaxViewerCount:
type: integer
sessionMaxViewerCount:
type: integer
online:
type: boolean
viewerCount:
type: integer
lastDisconnectTime:
type: string
nullable: true
format: date-time
examples:
online:
value:
lastConnectTime: '2020-10-03T21:36:22-05:00'
lastDisconnectTime: null
online: true
overallMaxViewerCount: 420
sessionMaxViewerCount: 12
viewerCount: 7
/api/customjavascript:
get:
summary: Custom Javascript to execute.
description: Returns custom Javascript that was set in the Owncast admin to be run in the Owncast frontend.
tags: ['Server']
responses:
'200':
description: ''
content:
application/javascript:
schema:
type: string
example: console.log("Hello World");
/api/chat/register:
post:
summary: Register a chat user
description: Register a user that returns an access token for accessing chat.
tags: ['Chat']
security:
- UserToken: []
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
displayName:
type: string
description: Optionally provide a display name you want to assign to this user when registering.
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The new user's id.
accessToken:
type: string
description: The access token used for accessing chat.
displayName:
type: string
description: The user-facing name displayed for this user.
/api/chat:
get:
summary: Chat Messages Backlog
description: Used to get chat messages prior to connecting to the websocket.
tags: ['Chat']
security:
- UserToken: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ChatMessageArray'
/api/yp:
get:
summary: Yellow Pages Information
description: Information to be used in the Yellow Pages service, a global directory of Owncast servers.
tags: ['Server']
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
name:
type: string
description:
type: string
logo:
type: string
nsfw:
type: boolean
tags:
type: array
items:
type: string
online:
type: boolean
viewerCount:
type: integer
overallMaxViewerCount:
type: integer
sessionMaxViewerCount:
type: integer
lastConnectTime:
type: string
nullable: true
format: date-time
/img/emoji/:
get:
parameters:
- name: name
in: path
description: Emoji image name
required: true
schema:
type: string
example: test.svg
summary: Get Emoji Image
description: Get an emoji image.
tags: ['Chat']
responses:
'200':
description: 'Returns a single image'
/api/emoji:
get:
summary: Get Custom Emoji
description: Get a list of custom emoji that are supported in chat.
tags: ['Chat']
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the Emoji
emoji:
type: string
description: The relative path to the Emoji image file
examples:
default:
value:
items:
- name: nicolas_cage_party
emoji: /img/emoji/nicolas_cage_party.gif
- name: parrot
emoji: /img/emoji/parrot.gif
/api/followers:
get:
summary: Get the public followers of this instance
responses:
'200':
description: Followers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Follower'
/api/remotefollow:
post:
summary: Return the information needed to redirect a user to a fediverse server to perform a remote follow action.
requestBody:
content:
application/json:
schema:
type: object
properties:
account:
description: The fediverse username@server.tld account that wants to perform the remote follow action.
type: string
example: johnsmith@fediverse.biz
responses:
'200':
description: Remote follow redirect details
content:
application/json:
schema:
type: object
properties:
redirectUrl:
description: The URL the frontend should redirect to
type: string
example: https://fediverse.biz/authorize_interaction?uri=https://my.owncast.server/federation/user/streamer
/api/chat/messagevisibility:
post:
summary: Update the visibility of chat messages.
description: Pass an array of IDs you want to change the chat visibility of.
requestBody:
content:
application/json:
schema:
type: object
properties:
visible:
type: boolean
description: Are these messages visible.
idArray:
type: array
items:
type: string
description: IDs of the chat messages you wish to change the visibility of.
tags: ['Moderation']
security:
- ModeratorUserToken: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
/api/chat/users/setenabled:
post:
summary: Disable (block) or re-enable a chat user.
requestBody:
content:
application/json:
schema:
type: object
properties:
userId:
type: string
description: User ID of the chat user you're changing.
enabled:
type: boolean
description: State of this user. False to block/disable.
tags: ['Moderation']
security:
- ModeratorUserToken: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
/api/admin/status:
get:
summary: 'Server status and broadcaster'
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
description: Server status and broadcaster details
content:
application/json:
schema:
type: object
properties:
broadcaster:
type: object
properties:
remoteAddr:
type: string
time:
type: string
format: date-time
streamDetails:
type: object
properties:
width:
type: integer
height:
type: integer
frameRate:
type: integer
videoBitrate:
type: integer
videoCodec:
type: string
audioBitrate:
type: integer
audioCodec:
type: string
encoder:
type: string
online:
type: boolean
description: Is a stream currently active
viewerCount:
type: integer
description: The current number of viewers
sessionPeakViewerCount:
type: integer
description: The peak number of viewers this streaming session
overallPeakViewerCount:
type: integer
description: The all-time peak number of viewers
versionNumber:
type: string
description: The current version of the owncast software
examples:
connected:
summary: 'Broadcaster Connected'
value:
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'
/api/admin/disconnect:
post:
summary: Disconnect Broadcaster
description: Disconnect the active inbound stream, if one exists, and terminate the broadcast.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
/api/admin/yp/reset:
post:
summary: Reset your YP registration key.
description: Used when there is a problem with your registration to the Owncast Directory via the YP APIs. This will reset your local registration key.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
/api/admin/chat/clients:
get:
summary: Return a list of currently connected clients
description: Return a list of currently connected clients with optional geo details.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/ClientsResponse'
/api/admin/users/disabled:
get:
summary: Return a list of currently connected clients
description: Return a list of currently connected clients with optional geo details.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/UsersResponse'
/api/admin/logs:
get:
summary: Return recent log entries
description: Returns server logs.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/LogsResponse'
/api/admin/logs/warnings:
get:
summary: Return recent warning and error logs.
description: Return recent warning and error logs.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/LogsResponse'
/api/admin/serverconfig:
get:
summary: Server Configuration
description: Get the current configuration of the Owncast server.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
instanceDetails:
$ref: '#/components/schemas/InstanceDetails'
ffmpegPath:
type: string
description: The path to the copy of ffmpeg that this server is using.
webServerPort:
type: integer
description: The port the public web server is listening on.
rtmpServerPort:
type: integer
description: The port the inbound RTMP broadcast should be sent to.
s3:
$ref: '#/components/schemas/S3'
videoSettings:
type: object
description: How the different variants of video streams are configured.
properties:
videoQualityVariants:
type: array
items:
$ref: '#/components/schemas/StreamQuality'
latencyLevel:
type: integer
description: The level of latency selected for streaming. Lower latency can create more buffering.
yp:
$ref: '#/components/schemas/YP'
/api/admin/chat/messages:
get:
summary: Chat messages, unfiltered.
description: Get a list of all chat messages with no filters applied.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
user:
$ref: '#/components/schemas/User'
body:
type: string
description: Escaped HTML of the chat message content.
id:
type: string
description: Unique ID of the chat message.
visible:
type: boolean
description: 'Should chat message be visibly rendered.'
timestamp:
type: string
format: date-time
/api/admin/chat/messagevisibility:
post:
summary: Update the visibility of chat messages.
description: Pass an array of IDs you want to change the chat visibility of.
requestBody:
content:
application/json:
schema:
type: object
properties:
visible:
type: boolean
description: Are these messages visible.
idArray:
type: array
items:
type: string
description: IDs of the chat messages you wish to change the visibility of.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
/api/admin/chat/users/setenabled:
post:
summary: Enable or disable a single user.
description: Enable or disable a single user. Disabling will also hide all the user's chat messages.
requestBody:
content:
application/json:
schema:
type: object
properties:
userId:
type: string
description: User ID to act upon.
example: 'yklw5Imng'
enabled:
type: boolean
description: Set the enabled state of this user.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
/api/admin/config/adminpass:
post:
summary: Set the admin password.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
/api/admin/config/streamkeys:
post:
summary: Set the stream keys.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StreamKeyArray'
/api/admin/config/pagecontent:
post:
summary: Set the custom page content.
description: Set the custom page content using markdown.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: '# Welcome to my cool server!
I _hope_ you enjoy it.'
/api/admin/config/streamtitle:
post:
summary: Set the stream title.
description: Set the title of the currently streaming content.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: Streaming my favorite game, Desert Bus.
/api/admin/config/name:
post:
summary: Set the server name.
description: Set the name associated with your server. Often is your name, username or identity.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
/api/admin/config/serversummary:
post:
summary: Set the server summary.
description: Set the summary of your server's streaming content.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: The best in Desert Bus Streaming
/api/admin/config/offlinemessage:
post:
summary: Set the offline message.
description: Set the message that is displayed when a stream is not live.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: Come back on Friday at 2pm, I'll be streaming then.
/api/admin/config/logo:
post:
summary: Set the server logo.
description: Set the logo for your server. Path is relative to webroot.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: '/img/mylogo.png'
/api/admin/config/tags:
post:
summary: Set the server tags.
description: Set the tags displayed for your server and the categories you can show up in on the directory.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value:
- games
- music
- streaming
/api/admin/config/ffmpegpath:
post:
summary: Set the ffmpeg binary path
description: Set the path for a specific copy of ffmpeg on your system.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: '/home/owncast/ffmpeg'
/api/admin/config/webserverport:
post:
summary: Set the owncast web port.
description: Set the port the owncast web server should listen on.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: 8080
/api/admin/config/rtmpserverport:
post:
summary: Set the inbound rtmp server port.
description: Set the port where owncast service will listen for inbound broadcasts.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: 1935
/api/admin/config/nsfw:
post:
summary: Mark if your stream is not safe for work
description: Mark if your stream can be consitered not safe for work. Used in different contexts, including the directory for filtering purposes.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: false
/api/admin/config/directoryenabled:
post:
summary: Set if this server supports the Owncast directory.
description: If set to true the server will attempt to register itself with the [Owncast Directory](https://directory.owncast.online). Off by default.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: true
/api/admin/config/serverurl:
post:
summary: Set the public url of this owncast server.
description: Set the public url of this owncast server. Used for the directory and optional integrations.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: https://live.mycoolserver.biz
/api/admin/config/video/streamlatencylevel:
post:
summary: Set the latency level for the stream.
description: Sets the latency level that determines how much video is buffered between the server and viewer. Less latency can end up with more buffering.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
type: object
properties:
value:
description: The latency level
type: integer
example:
value: 4
/api/admin/config/video/streamoutputvariants:
post:
summary: Set the configuration of your stream output.
description: Sets the detailed configuration for all of the stream variants you support.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value:
- framerate: 30
videoPassthrough: false
videoBitrate: 1800
cpuUsageLevel: 2
audioPassthrough: true
- framerate: 24
videoPassthrough: false
videoBitrate: 1000
cpuUsageLevel: 3
audioPassthrough: true
/api/admin/config/video/codec:
post:
summary: Set the video codec.
description: 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.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
type: object
properties:
value:
description: The video codec to change to.
type: string
example:
value: libx264
/api/admin/config/s3:
post:
summary: Set your storage configuration.
description: Sets your S3 storage provider configuration details to enable external storage.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value:
enabled: true
endpoint: https://s3.us-west-000.backblazeb2.com
accessKey: e1ac500y7000500047156bd060
secret: 'H8FH8eSxM2K/S42CUg5K000Tt4WY2fI'
bucket: 'video'
region: us-west-000
/api/admin/config/socialhandles:
post:
summary: Set your social handles.
description: Sets the external links to social networks and profiles.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value:
- platform: github
url: https://github.com/owncast/owncast
- platform: mastodon
url: https://mastodon.social/@gabek
/api/admin/config/customstyles:
post:
summary: Custom CSS styles to be used in the web front endpoints.
description: Save a string containing CSS to be inserted in to the web frontend page.
tags: ['Admin']
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: 'body { color: orange; background: black; }'
/api/admin/config/customjavascript:
post:
summary: Custom Javascript to be inserted into the frontend
description: Save a string containing Javascript to be inserted in to the web frontend page.
tags: ['Admin']
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/javascript:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: console.log('Hello world.');
/api/admin/config/appearance:
post:
summary: Save a map of variables and values to be used in the frontend.
description: These values will override the default values in the frontend.
tags: ['Admin']
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
type: object
properties:
value:
type: object
example:
value:
theme-color-components-primary-button-background: '#ff0000'
theme-color-components-chat-background: '#000000'
/api/admin/viewersOverTime:
get:
summary: Viewers Over Time
description: Get the tracked viewer count over the collected period.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TimestampedValue'
examples:
default:
value:
- time: '2020-10-03T21:41:00.381996-05:00'
value: 50
- time: '2020-10-03T21:42:00.381996-05:00'
value: 52
/api/admin/hardwarestats:
get:
summary: Hardware Stats
description: 'Get the CPU, Memory and Disk utilization levels over the collected period.'
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
cpu:
type: array
items:
$ref: '#/components/schemas/TimestampedValue'
memory:
type: array
items:
$ref: '#/components/schemas/TimestampedValue'
disk:
type: array
items:
$ref: '#/components/schemas/TimestampedValue'
examples:
default:
value:
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
/api/admin/config/hideviewercount:
post:
summary: Enable or disable showing the viewer count.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanValue'
/api/admin/config/federation/enable:
post:
summary: Enable or disable federated social features.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanValue'
/api/admin/config/federation/private:
post:
summary: Enable or disable private federation mode.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanValue'
/api/admin/config/federation/showengagement:
post:
summary: Enable or disable Federation activity showing in chat.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BooleanValue'
/api/admin/config/federation/username:
post:
summary: Set the username you are seen as on the fediverse.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
/api/admin/config/federation/livemessage:
post:
summary: Set the message sent to the fediverse when this instance goes live.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
/api/admin/config/federation/blockdomains:
post:
summary: Save a collection of domains that should be ignored on the fediverse.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value:
- guns.eagles.biz
- freedom.us
/api/admin/federation/send:
post:
summary: Manually send a message to the fediverse from this instance.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: I'm still streaming, you should come visit.
/api/admin/federation/actions:
get:
summary: Get a list of accepted actions that took place on the Fediverse.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
description: Actions previously handled.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FederatedAction'
/api/admin/emoji/upload:
post:
summary: Upload a single emoji image.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
/api/admin/emoji/delete:
post:
summary: Delete a single emoji image.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
type: object
example:
name: test.svg
/api/integrations/streamtitle:
post:
summary: Set the stream title.
description: Set the title of the currently streaming content.
tags: ['Integrations']
security:
- AccessToken: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigValue'
example:
value: Streaming my favorite game, Desert Bus.
/api/integrations/chat/send:
post:
summary: Send a chat message.
description: Send a chat message on behalf of a 3rd party integration, bot or service.
tags: ['Integrations']
security:
- AccessToken: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
body:
type: string
description: The message text that will be sent as the user.
responses:
'200':
description: Message was sent.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: sent
/api/integrations/chat/system:
post:
summary: Send a system chat message.
description: Send a chat message on behalf of the system/server.
tags: ['Integrations']
security:
- AccessToken: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
body:
type: string
description: The message text that will be sent as the system user.
responses:
'200':
description: Message was sent.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: sent
/api/integrations/chat/action:
post:
summary: Send a chat action.
description: Send an action that took place to the chat.
tags: ['Integrations']
security:
- AccessToken: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- 'body'
properties:
body:
type: string
description: The message text that will be sent as the system user.
example: 'rolled a 15 on the dice'
author:
type: string
description: An optional user name that performed the action.
example: 'JohnSmith'
responses:
'200':
description: Message was sent.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: sent
/api/integrations/chat/system/client/{clientId}:
post:
summary: Send system chat message to a client, identified by its ClientId
description: Send a chat message on behalf of the system/server to a single client.
tags: ['Integrations']
security:
- AccessToken: []
parameters:
- name: clientId
in: path
description: Client ID (a unique numeric Id, identifying the client connection)
required: true
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- 'body'
properties:
body:
type: string
description: The message text that will be sent to the client.
example: 'What a beautiful day. I love it'
responses:
'200':
description: Message was sent.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
messages:
type: string
example: sent
'500':
description: Message was not sent to the client
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: message explaining what went wrong sending the message to the client
/api/admin/accesstokens/create:
post:
summary: Create an access token.
description: Create a single access token that has access to the access scopes provided.
tags: ['Integrations']
security:
- AdminBasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The human-readable name to give this access token.
scopes:
type: array
items:
type: string
responses:
'200':
description: Token was created.
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: your new token
token:
type: string
example: 'zG2xO-mHTFnelCp5xaIkYEFWcPhoOswOSRmFC1BkI='
/api/admin/accesstokens/delete:
post:
summary: Delete an access token.
description: Delete a single access token.
tags: ['Integrations']
security:
- AdminBasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: The token to delete
responses:
'200':
description: Token was deleted.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: deleted token
/api/admin/accesstokens:
get:
summary: Return all access tokens.
description: Return all of the available access tokens.
tags: ['Integrations']
security:
- AdminBasicAuth: []
responses:
'200':
description: Tokens are returned
content:
application/json:
schema:
type: array
items:
type: string
/api/admin/webhooks:
get:
summary: Return all webhooks.
description: Return all of the configured webhooks for external events.
tags: ['Admin']
security:
- AdminBasicAuth: []
responses:
'200':
description: Webhooks are returned
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
/api/admin/config/externalactions:
post:
summary: Set external action URLs.
description: Set a collection of external action URLs that are displayed in the UI.
tags: ['Admin', 'Integrations']
security:
- AdminBasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: object
properties:
url:
type: string
description: URL of the external action content.
title:
type: string
description: The title to put on the external action button.
description:
type: string
description: Optional additional description to display in the UI.
icon:
type: string
description: The URL to an image to place on the external action button.
color:
type: string
description: Optional color to use for drawing the action button.
openExternally:
type: boolean
description: If set this action will open in a new browser tab instead of an internal modal.
responses:
'200':
description: Actions have been updated.
/api/admin/webhooks/delete:
post:
summary: Delete a single webhook.
description: Delete a single webhook by its ID.
tags: ['Admin']
security:
- AdminBasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The webhook id to delete
responses:
'200':
description: Webhook is deleted
/api/admin/webhooks/create:
post:
summary: Create a webhook.
description: Create a single webhook that acts on the requested events.
tags: ['Admin']
security:
- AdminBasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
url:
type: string
description: The url to post the events to.
events:
description: The events to be notified about.
type: array
items:
type: string
responses:
'200':
description: Token was created.
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: your new token
token:
type: string
example: 'zG2xO-mHTFnelCp5xaIkYEFWcPhoOswOSRmFC1BkI='
/api/integrations/clients:
get:
summary: Return a list of currently connected clients
description: Return a list of currently connected clients with optional geo details.
tags: ['Integrations']
security:
- AccessToken: []
responses:
'200':
$ref: '#/components/responses/ClientsResponse'
/api/integrations/chat:
get:
summary: Historical Chat Messages
description: Used to get the backlog of chat messages.
tags: ['Integrations']
security:
- AccessToken: []
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
user:
$ref: '#/components/schemas/User'
body:
type: string
description: Escaped HTML of the chat message content.
id:
type: string
description: Unique ID of the chat message.
visible:
type: boolean
description: 'Should chat message be visibly rendered.'
timestamp:
type: string
format: date-time
/api/integrations/chat/messagevisibility:
post:
summary: Update the visibility of chat messages.
description: Pass an array of IDs you want to change the chat visibility of.
requestBody:
content:
application/json:
schema:
type: object
properties:
visible:
type: boolean
description: Are these messages visible.
idArray:
type: array
items:
type: string
description: IDs of the chat messages you wish to change the visibility of.
tags: ['Integrations']
security:
- AccessToken: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
/api/admin/chat/users/setmoderator:
post:
summary: Set moderator privileges on a chat users.
description: Give a chat user ID and be able to grant or remove moderator privileges to this user.
requestBody:
content:
application/json:
schema:
type: object
properties:
userId:
type: string
description: User ID of the chat user you want to change moderation status of.
example: xJ84_48Ghj
isModerator:
type: boolean
description: The moderator status of this user.
example: true
tags: ['Admin', 'Moderation']
security:
- AdminBasicAuth: []
responses:
'200':
$ref: '#/components/responses/BasicResponse'
/api/admin/chat/users/moderators:
get:
tags: ['Admin', 'Moderation']
security:
- AdminBasicAuth: []
summary: Get a list of chat moderator users.
responses:
'200':
description: List of moderators
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
/api/moderation/chat/user/:
get:
tags: ['Moderation']
parameters:
- name: name
in: path
description: User ID
required: true
schema:
type: string
example: USER-ID
responses:
'200':
description: User
content:
application/json:
schema:
type: object
properties:
user:
$ref: '#/components/schemas/User'
connectClients:
type: array
items:
$ref: '#/components/schemas/Client'
messages:
$ref: '#/components/schemas/ChatMessageArray'
/api/admin/followers:
get:
tags: ['Admin']
security:
- AdminBasicAuth: []
summary: Get the followers of this instance
responses:
'200':
description: Followers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Follower'
/api/admin/followers/pending:
get:
tags: ['Admin']
security:
- AdminBasicAuth: []
summary: Get a list of follow requests that are pending.
responses:
'200':
description: Followers
$ref: '#/components/schemas/FollowerArray'
/api/admin/followers/blocked:
get:
tags: ['Admin']
security:
- AdminBasicAuth: []
summary: Get a list of follow requests that have been blocked/rejected.
responses:
'200':
description: Follower requests that have been rejected or blocked.
$ref: '#/components/schemas/FollowerArray'
/api/admin/followers/approve:
post:
tags: ['Admin']
security:
- AdminBasicAuth: []
summary: Approve a pending follow request.
requestBody:
content:
application/json:
schema:
type: object
properties:
actorIRI:
type: string
description: The requestor's remote IRI used to identify the user.
responses:
'200':
description: The request has been successfully approved.
$ref: '#/components/responses/BasicResponse'
/api/admin/config/chat/suggestedusernames:
post:
tags: ['Admin']
security:
- AdminBasicAuth: []
summary: A list of names to select from randomly for new chat users.
requestBody:
content:
application/json:
schema:
type: object
properties:
value:
type: array
items:
type: string
responses:
'200':
description: The list of default names have been updated.
$ref: '#/components/responses/BasicResponse'
/api/admin/prometheus:
get:
tags: ['Admin']
security:
- AdminBasicAuth: []
summary: Return Prometheus-compatible scraper metrics.
responses:
'200':
description: Prometheus-compatible scraper values.