diff --git a/docs/api/index.html b/docs/api/index.html
index 263c2c20d..5f7ee1bd6 100644
--- a/docs/api/index.html
+++ b/docs/api/index.html
@@ -13,21 +13,27 @@
}
- Owncast (0.0.11) Download OpenAPI specification:Download
Owncast is a self-hosted live video and web chat server for use with existing popular broadcasting software. The following APIs represent the state in the development branch.
-
AdminBasicAuthThe username for admin basic auth is admin
and the password is the stream key.
-
Security Scheme Type HTTP HTTP Authorization Scheme basic
AccessToken3rd party integration auth where a service user must provide an access token.
-
Security Scheme Type HTTP HTTP Authorization Scheme bearer
UserTokenA standard user must provide a valid access token.
-
Security Scheme Type API Key Query parameter name: accessToken
ModeratorUserTokenA moderator user must provide a valid access token.
-
Security Scheme Type API Key Query parameter name: accessToken
Admin operations requiring authentication.
-
Server status and broadcaster Responses 200 Server status and broadcaster details
- Response samples Content type application/json
Copy
Expand all Collapse all { "broadcaster" :
{ "remoteAddr" : "172.217.164.110" ,
"time" : "2020-10-06T23:20:44.588649-07:00" ,
} , "online" : true ,
"viewerCount" : 3 ,
"overallPeakViewerCount" : 4 ,
"sessionPeakViewerCount" : 4 ,
"versionNumber" : "0.0.3"
}
Disconnect Broadcaster post /api/admin/disconnect Disconnect the active inbound stream, if one exists, and terminate the broadcast.
-
Responses 200 Operation Success/Failure Response
- Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all 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.
-
Responses 200 Operation Success/Failure Response
- Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Return a list of currently connected clients get /api/admin/chat/clients Return a list of currently connected clients with optional geo details.
-
Responses 200 Successful response of an array of clients
- Response samples Content type application/json
Copy
Expand all Collapse all [ { "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" ,
"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 get /api/admin/users/disabled
/api/admin/users/disabled
Return a list of currently connected clients with optional geo details.
-
Responses 200 A collection of users.
- Response samples Content type application/json
Copy
Expand all Collapse all [ { "id" : "yklw5Imng" ,
"displayName" : "awesome-pizza" ,
"displayColor" : 42 ,
"createdAt" : "2019-08-24T14:15:22Z" ,
"previousNames" : "awesome-pizza,user42" ,
} ]
Return recent log entries Responses 200 Response of server log entries
- Response samples Content type application/json
Copy
Expand all Collapse all [ { "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. get /api/admin/logs/warnings Return recent warning and error logs.
-
Responses 200 Response of server log entries
- Response samples Content type application/json
Copy
Expand all Collapse all [ { "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 /api/admin/serverconfig Get the current configuration of the Owncast server.
-
Response samples Content type application/json
Copy
Expand all Collapse all { "instanceDetails" :
{ "name" : "string" ,
"summary" : "string" ,
"logo" : "string" ,
"extraPageContent" : "<p>This page is <strong>super</strong> cool!" ,
"version" : "Owncast v0.0.3-macOS (ef3796a033b32a312ebf5b334851cbf9959e7ecb)"
} , "ffmpegPath" : "string" ,
"webServerPort" : 0 ,
"rtmpServerPort" : 0 ,
"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 /api/admin/chat/messages Get a list of all chat messages with no filters applied.
-
Response samples Content type application/json
Copy
Expand all Collapse all Update the visibility of chat messages. post /api/admin/chat/updatemessagevisibility
/api/admin/chat/updatemessagevisibility
Pass an array of IDs you want to change the chat visibility of.
-
Request Body schema: application/json
visible boolean
Are these messages visible.
-
idArray
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Enable or disable a single user. post /api/admin/chat/users/setenabled
/api/admin/chat/users/setenabled
Enable or disable a single user. Disabling will also hide all the user's chat messages.
-
Request Body schema: application/json
userId enabled boolean
Set the enabled state of this user.
-
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all { "userId" : "yklw5Imng" ,
"enabled" : true
}
Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the stream key. post /api/admin/config/key Set the stream key. Also used as the admin password.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the custom page content. post /api/admin/config/pagecontent
/api/admin/config/pagecontent
Set the custom page content using markdown.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all "# Welcome to my cool server!<br><br>I _hope_ you enjoy it."
Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the stream title. post /api/admin/config/streamtitle
/api/admin/config/streamtitle
Set the title of the currently streaming content.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the server name. post /api/admin/config/name Set the name associated with your server. Often is your name, username or identity.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the server summary. post /api/admin/config/serversummary
/api/admin/config/serversummary
Set the summary of your server's streaming content.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the server logo. post /api/admin/config/logo Set the logo for your server. Path is relative to webroot.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the server tags. post /api/admin/config/tags Set the tags displayed for your server and the categories you can show up in on the directory.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all { "value" :
[ "games" ,
"music" ,
"streaming"
] }
Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the ffmpeg binary path post /api/admin/config/ffmpegpath
/api/admin/config/ffmpegpath
Set the path for a specific copy of ffmpeg on your system.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the owncast web port. post /api/admin/config/webserverport
/api/admin/config/webserverport
Set the port the owncast web server should listen on.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the inbound rtmp server port. post /api/admin/config/rtmpserverport
/api/admin/config/rtmpserverport
Set the port where owncast service will listen for inbound broadcasts.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Mark if your stream is not safe for work post /api/admin/config/nsfw Mark if your stream can be consitered not safe for work. Used in different contexts, including the directory for filtering purposes.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set if this server supports the Owncast directory. post /api/admin/config/directoryenabled
/api/admin/config/directoryenabled
If set to true the server will attempt to register itself with the Owncast Directory . Off by default.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the public url of this owncast server. post /api/admin/config/serverurl
/api/admin/config/serverurl
Set the public url of this owncast server. Used for the directory and optional integrations.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the latency level for the stream. post /api/admin/config/video/streamlatencylevel
/api/admin/config/video/streamlatencylevel
Sets the latency level that determines how much video is buffered between the server and viewer. Less latency can end up with more buffering.
-
Request Body schema: application/json
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the configuration of your stream output. post /api/admin/config/video/streamoutputvariants
/api/admin/config/video/streamoutputvariants
Sets the detailed configuration for all of the stream variants you support.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the video codec. post /api/admin/config/video/codec
/api/admin/config/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.
-
Request Body schema: application/json
value string
The video codec to change to.
-
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set your storage configration. Sets your S3 storage provider configuration details to enable external storage.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all { "value" :
{ "enabled" : true ,
"accessKey" : "e1ac500y7000500047156bd060" ,
"secret" : "H8FH8eSxM2K/S42CUg5K000Tt4WY2fI" ,
"bucket" : "video" ,
"region" : "us-west-000"
} }
Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set your social handles. post /api/admin/config/socialhandles
/api/admin/config/socialhandles
Sets the external links to social networks and profiles.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Custom CSS styles to be used in the web front endpoints. post /api/admin/config/customstyles
/api/admin/config/customstyles
Save a string containing CSS to be inserted in to the web frontend page.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Viewers Over Time get /api/admin/viewersOverTime
/api/admin/viewersOverTime
Get the tracked viewer count over the collected period.
-
Response samples Content type application/json
Copy
Expand all Collapse all Hardware Stats get /api/admin/hardwarestats Get the CPU, Memory and Disk utilization levels over the collected period.
-
Response samples Content type application/json
Copy
Expand all Collapse all Enable or disable federated social features. post /api/admin/config/federation/enable
/api/admin/config/federation/enable
Request Body schema: application/json
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Enable or disable private federation mode. post /api/admin/config/federation/private
/api/admin/config/federation/private
Request Body schema: application/json
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Enable or disable Federation activity showing in chat. post /api/admin/config/federation/showengagement
/api/admin/config/federation/showengagement
Request Body schema: application/json
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the username you are seen as on the fediverse. post /api/admin/config/federation/username
/api/admin/config/federation/username
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set the message sent to the fediverse when this instance goes live. post /api/admin/config/federation/livemessage
/api/admin/config/federation/livemessage
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Save a collection of domains that should be ignored on the fediverse. post /api/admin/config/federation/blockdomains
/api/admin/config/federation/blockdomains
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all { "value" :
[ "guns.eagles.biz" ,
"freedom.us"
] }
Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Manually send a message to the fediverse from this instance. post /api/admin/federation/send
/api/admin/federation/send
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Get a list of accepted actions that took place on the Fediverse. get /api/admin/federation/actions
/api/admin/federation/actions
Responses 200 Actions previously handled.
- Response samples Content type application/json
Copy
Expand all Collapse all Return all webhooks. Return all of the configured webhooks for external events.
-
Responses 200 Webhooks are returned
- Response samples Content type application/json
Copy
Expand all Collapse all Set external action URLs. post /api/admin/config/externalactions
/api/admin/config/externalactions
Set a collection of external action URLs that are displayed in the UI.
-
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 200 Actions have been updated.
- Request samples Content type application/json
Copy
Expand all Collapse all [ { "url" : "string" ,
"title" : "string" ,
"description" : "string" ,
"icon" : "string" ,
"color" : "string" ,
"openExternally" : true
} ]
Delete a single webhook. post /api/admin/webhooks/delete
/api/admin/webhooks/delete
Delete a single webhook by its ID.
-
Request Body schema: application/json
id string
The webhook id to delete
-
Request samples Content type application/json
Copy
Expand all Collapse all Create a webhook. post /api/admin/webhooks/create
/api/admin/webhooks/create
Create a single webhook that acts on the requested events.
-
Request Body schema: application/json
url string
The url to post the events to.
-
events Array of strings
The events to be notified about.
-
Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Copy
Expand all Collapse all Set moderator priviledges on a chat users. post /api/admin/chat/users/setmoderator
/api/admin/chat/users/setmoderator
Give a chat user ID and be able to grant or remove moderator priviledges to this user.
-
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 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all { "userId" : "xJ84_48Ghj" ,
"isModerator" : true
}
Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Get a list of chat moderator users. get /api/admin/chat/users/moderators
/api/admin/chat/users/moderators
Response samples Content type application/json
Copy
Expand all Collapse all [ { "id" : "yklw5Imng" ,
"displayName" : "awesome-pizza" ,
"displayColor" : 42 ,
"createdAt" : "2019-08-24T14:15:22Z" ,
"previousNames" : "awesome-pizza,user42" ,
} ]
Get the followers of this instance Response samples Content type application/json
Copy
Expand all Collapse all Get a list of follow requests that are pending. get /api/admin/followers/pending
/api/admin/followers/pending
Get a list of follow requests that have been blocked/rejected. get /api/admin/followers/blocked
/api/admin/followers/blocked
Approve a pending follow request. post /api/admin/followers/approve
/api/admin/followers/approve
Request Body schema: application/json
actorIRI string
The requestor's remote IRI used to identify the user.
-
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all A list of names to select from randomly for new chat users. post /api/admin/config/chat/suggestedusernames
/api/admin/config/chat/suggestedusernames
Request Body schema: application/json
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Endpoints related to the chat interface.
-
Register a chat user Register a user that returns an access token for accessing chat.
-
Request Body schema: application/json
displayName string
Optionally provide a display name you want to assign to this user when registering.
-
Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Copy
Expand all Collapse all { "id" : "string" ,
"accessToken" : "string" ,
"displayName" : "string"
}
Chat Messages Backlog Used to get chat messages prior to connecting to the websocket.
-
Response samples Content type application/json
Copy
Expand all Collapse all Get Custom Emoji Get a list of custom emoji that are supported in chat.
-
Response samples Content type application/json
Copy
Expand all Collapse all APIs built to allow 3rd parties to interact with an Owncast server.
-
Set the stream title. post /api/integrations/streamtitle
/api/integrations/streamtitle
Set the title of the currently streaming content.
-
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Send a chat message. post /api/integrations/chat/send
/api/integrations/chat/send
Send a chat message on behalf of a 3rd party integration, bot or service.
-
Request Body schema: application/json
body string
The message text that will be sent as the user.
-
Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Copy
Expand all Collapse all { "success" : true ,
"message" : "sent"
}
Send a system chat message. post /api/integrations/chat/system
/api/integrations/chat/system
Send a chat message on behalf of the system/server.
-
Request Body schema: application/json
body string
The message text that will be sent as the system user.
-
Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Copy
Expand all Collapse all { "success" : true ,
"message" : "sent"
}
Send a chat action. post /api/integrations/chat/action
/api/integrations/chat/action
Send an action that took place to the chat.
-
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.
-
Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Copy
Expand all Collapse all { "success" : true ,
"message" : "sent"
}
Send system chat message to a client, identified by its ClientId post /api/integrations/chat/system/client/{clientId}
/api/integrations/chat/system/client/{clientId}
Send a chat message on behalf of the system/server to a single client.
-
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 500 Message was not sent to the client
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Copy
Expand all Collapse all { "success" : true ,
"messages" : "sent"
}
Create an access token. post /api/admin/accesstokens/create
/api/admin/accesstokens/create
Create a single access token that has access to the access scopes provided.
-
Request Body schema: application/json
name string
The human-readable name to give this access token.
-
scopes
Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Copy
Expand all Collapse all Delete an access token. post /api/admin/accesstokens/delete
/api/admin/accesstokens/delete
Delete a single access token.
-
Request Body schema: application/json
Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Copy
Expand all Collapse all Return all access tokens. get /api/admin/accesstokens Return all of the available access tokens.
-
Responses 200 Tokens are returned
- Response samples Content type application/json
Copy
Expand all Collapse all Set external action URLs. post /api/admin/config/externalactions
/api/admin/config/externalactions
Set a collection of external action URLs that are displayed in the UI.
-
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 200 Actions have been updated.
- Request samples Content type application/json
Copy
Expand all Collapse all [ { "url" : "string" ,
"title" : "string" ,
"description" : "string" ,
"icon" : "string" ,
"color" : "string" ,
"openExternally" : true
} ]
Return a list of currently connected clients get /api/integrations/clients
/api/integrations/clients
Return a list of currently connected clients with optional geo details.
-
Responses 200 Successful response of an array of clients
- Response samples Content type application/json
Copy
Expand all Collapse all [ { "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" ,
"user" :
{ "id" : "yklw5Imng" ,
"displayName" : "awesome-pizza" ,
"displayColor" : 42 ,
"createdAt" : "2021-07-08T20:21:25.303402404-07:00" ,
"previousNames" : "awesome-pizza,coolPerson23"
} } ]
Historical Chat Messages get /api/integrations/chat Used to get the backlog of chat messages.
-
Response samples Content type application/json
Copy
Expand all Collapse all Update the visibility of chat messages. post /api/integrations/chat/updatemessagevisibility
/api/integrations/chat/updatemessagevisibility
Pass an array of IDs you want to change the chat visibility of.
-
Request Body schema: application/json
visible boolean
Are these messages visible.
-
idArray
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Chat-related actions that can take place by a moderator.
-
Update the visibility of chat messages. post /api/chat/updatemessagevisibility
/api/chat/updatemessagevisibility
Pass an array of IDs you want to change the chat visibility of.
-
Request Body schema: application/json
visible boolean
Are these messages visible.
-
idArray
Responses 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Disable (block) or re-enable a chat user. post /api/chat/users/setenabled
/api/chat/users/setenabled
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 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all { "userId" : "string" ,
"enabled" : true
}
Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Set moderator priviledges on a chat users. post /api/admin/chat/users/setmoderator
/api/admin/chat/users/setmoderator
Give a chat user ID and be able to grant or remove moderator priviledges to this user.
-
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 200 Operation Success/Failure Response
- Request samples Content type application/json
Copy
Expand all Collapse all { "userId" : "xJ84_48Ghj" ,
"isModerator" : true
}
Response samples Content type application/json
Example Operation succeeded.
Operation failed.
Copy
Expand all Collapse all Get a list of chat moderator users. get /api/admin/chat/users/moderators
/api/admin/chat/users/moderators
Response samples Content type application/json
Copy
Expand all Collapse all [ { "id" : "yklw5Imng" ,
"displayName" : "awesome-pizza" ,
"displayColor" : 42 ,
"createdAt" : "2019-08-24T14:15:22Z" ,
"previousNames" : "awesome-pizza,user42" ,
} ]
Information The client configuration. Information useful for the user interface.
-
Response samples Content type application/json
Copy
Expand all Collapse all { "name" : "string" ,
"summary" : "string" ,
"logo" : "string" ,
"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.
-
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.
-
Response samples Content type application/json
Copy
Expand all Collapse all { "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.
-
Response samples Content type application/json
Copy
Expand all Collapse all { "name" : "string" ,
"description" : "string" ,
"logo" : "string" ,
"nsfw" : true ,
"online" : true ,
"viewerCount" : 0 ,
"overallMaxViewerCount" : 0 ,
"sessionMaxViewerCount" : 0 ,
"lastConnectTime" : "2019-08-24T14:15:22Z"
}
Get the public followers of this instance Response samples Content type application/json
Copy
Expand all Collapse all Return the information needed to redirect a user to a fediverse server to perform a remote follow action. Request Body schema: application/json
Responses 200 Remote follow redirect details
- Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Copy
Expand all Collapse all
+ " fill="currentColor">
Owncast (0.0.12) Download OpenAPI specification:Download
Owncast is a self-hosted live video and web chat server for use with existing popular broadcasting software.
+
Admin operations requiring authentication.
+
Server status and broadcaster Responses 200 Server status and broadcaster details
+ Response samples Content type application/json
Copy
Expand all Collapse all { "broadcaster" :
{ "remoteAddr" : "172.217.164.110" ,
"time" : "2020-10-06T23:20:44.588649-07:00" ,
} , "online" : true ,
"viewerCount" : 3 ,
"overallPeakViewerCount" : 4 ,
"sessionPeakViewerCount" : 4 ,
"versionNumber" : "0.0.3"
}
Disconnect Broadcaster post /api/admin/disconnect Disconnect the active inbound stream, if one exists, and terminate the broadcast.
+
Responses 200 Operation Success/Failure Response
+ Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. 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.
+
Responses 200 Operation Success/Failure Response
+ Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Return a list of currently connected clients get /api/admin/chat/clients Return a list of currently connected clients with optional geo details.
+
Responses 200 Successful response of an array of clients
+ Response samples Content type application/json
Copy
Expand all Collapse all [ { "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" ,
"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 get /api/admin/users/disabled
/api/admin/users/disabled
Return a list of currently connected clients with optional geo details.
+
Responses 200 A collection of users.
+ Response samples Content type application/json
Copy
Expand all Collapse all [ { "id" : "yklw5Imng" ,
"displayName" : "awesome-pizza" ,
"displayColor" : 42 ,
"createdAt" : "2019-08-24T14:15:22Z" ,
"previousNames" : "awesome-pizza,user42" ,
} ]
Return recent log entries Responses 200 Response of server log entries
+ Response samples Content type application/json
Copy
Expand all Collapse all [ { "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. get /api/admin/logs/warnings Return recent warning and error logs.
+
Responses 200 Response of server log entries
+ Response samples Content type application/json
Copy
Expand all Collapse all [ { "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 /api/admin/serverconfig Get the current configuration of the Owncast server.
+
Response samples Content type application/json
Copy
Expand all Collapse all { "instanceDetails" :
{ "name" : "string" ,
"summary" : "string" ,
"logo" : "string" ,
"extraPageContent" : "<p>This page is <strong>super</strong> cool!" ,
"version" : "Owncast v0.0.3-macOS (ef3796a033b32a312ebf5b334851cbf9959e7ecb)"
} , "ffmpegPath" : "string" ,
"webServerPort" : 0 ,
"rtmpServerPort" : 0 ,
"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 /api/admin/chat/messages Get a list of all chat messages with no filters applied.
+
Response samples Content type application/json
Copy
Expand all Collapse all Update the visibility of chat messages. post /api/admin/chat/updatemessagevisibility
/api/admin/chat/updatemessagevisibility
Pass an array of IDs you want to change the chat visibility of.
+
Request Body schema: application/json
visible boolean
Are these messages visible.
+
idArray
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Enable or disable a single user. post /api/admin/chat/users/setenabled
/api/admin/chat/users/setenabled
Enable or disable a single user. Disabling will also hide all the user's chat messages.
+
Request Body schema: application/json
userId enabled boolean
Set the enabled state of this user.
+
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
{ "userId" : "yklw5Imng" ,
"enabled" : true
}
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the stream key. post /api/admin/config/key Set the stream key. Also used as the admin password.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the custom page content. post /api/admin/config/pagecontent
/api/admin/config/pagecontent
Set the custom page content using markdown.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ 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 Operation succeeded. Operation failed. Operation succeeded. Set the stream title. post /api/admin/config/streamtitle
/api/admin/config/streamtitle
Set the title of the currently streaming content.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the server name. post /api/admin/config/name Set the name associated with your server. Often is your name, username or identity.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the server summary. post /api/admin/config/serversummary
/api/admin/config/serversummary
Set the summary of your server's streaming content.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the server logo. post /api/admin/config/logo Set the logo for your server. Path is relative to webroot.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the server tags. post /api/admin/config/tags Set the tags displayed for your server and the categories you can show up in on the directory.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Copy
Expand all Collapse all { "value" :
[ "games" ,
"music" ,
"streaming"
] }
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the ffmpeg binary path post /api/admin/config/ffmpegpath
/api/admin/config/ffmpegpath
Set the path for a specific copy of ffmpeg on your system.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the owncast web port. post /api/admin/config/webserverport
/api/admin/config/webserverport
Set the port the owncast web server should listen on.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the inbound rtmp server port. post /api/admin/config/rtmpserverport
/api/admin/config/rtmpserverport
Set the port where owncast service will listen for inbound broadcasts.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Mark if your stream is not safe for work post /api/admin/config/nsfw Mark if your stream can be consitered not safe for work. Used in different contexts, including the directory for filtering purposes.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set if this server supports the Owncast directory. post /api/admin/config/directoryenabled
/api/admin/config/directoryenabled
If set to true the server will attempt to register itself with the Owncast Directory . Off by default.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the public url of this owncast server. post /api/admin/config/serverurl
/api/admin/config/serverurl
Set the public url of this owncast server. Used for the directory and optional integrations.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the latency level for the stream. post /api/admin/config/video/streamlatencylevel
/api/admin/config/video/streamlatencylevel
Sets the latency level that determines how much video is buffered between the server and viewer. Less latency can end up with more buffering.
+
Request Body schema: application/json
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the configuration of your stream output. post /api/admin/config/video/streamoutputvariants
/api/admin/config/video/streamoutputvariants
Sets the detailed configuration for all of the stream variants you support.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the video codec. post /api/admin/config/video/codec
/api/admin/config/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.
+
Request Body schema: application/json
value string
The video codec to change to.
+
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set your storage configration. Sets your S3 storage provider configuration details to enable external storage.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Copy
Expand all Collapse all { "value" :
{ "enabled" : true ,
"accessKey" : "e1ac500y7000500047156bd060" ,
"secret" : "H8FH8eSxM2K/S42CUg5K000Tt4WY2fI" ,
"bucket" : "video" ,
"region" : "us-west-000"
} }
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set your social handles. post /api/admin/config/socialhandles
/api/admin/config/socialhandles
Sets the external links to social networks and profiles.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Custom CSS styles to be used in the web front endpoints. post /api/admin/config/customstyles
/api/admin/config/customstyles
Save a string containing CSS to be inserted in to the web frontend page.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Viewers Over Time get /api/admin/viewersOverTime
/api/admin/viewersOverTime
Get the tracked viewer count over the collected period.
+
Response samples Content type application/json
Copy
Expand all Collapse all Hardware Stats get /api/admin/hardwarestats Get the CPU, Memory and Disk utilization levels over the collected period.
+
Response samples Content type application/json
Copy
Expand all Collapse all Enable or disable federated social features. post /api/admin/config/federation/enable
/api/admin/config/federation/enable
Request Body schema: application/json
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Enable or disable private federation mode. post /api/admin/config/federation/private
/api/admin/config/federation/private
Request Body schema: application/json
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Enable or disable Federation activity showing in chat. post /api/admin/config/federation/showengagement
/api/admin/config/federation/showengagement
Request Body schema: application/json
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the username you are seen as on the fediverse. post /api/admin/config/federation/username
/api/admin/config/federation/username
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set the message sent to the fediverse when this instance goes live. post /api/admin/config/federation/livemessage
/api/admin/config/federation/livemessage
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Save a collection of domains that should be ignored on the fediverse. post /api/admin/config/federation/blockdomains
/api/admin/config/federation/blockdomains
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Copy
Expand all Collapse all { "value" :
[ "guns.eagles.biz" ,
"freedom.us"
] }
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Manually send a message to the fediverse from this instance. post /api/admin/federation/send
/api/admin/federation/send
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Get a list of accepted actions that took place on the Fediverse. get /api/admin/federation/actions
/api/admin/federation/actions
Responses 200 Actions previously handled.
+ Response samples Content type application/json
Copy
Expand all Collapse all Return all webhooks. Return all of the configured webhooks for external events.
+
Responses 200 Webhooks are returned
+ Response samples Content type application/json
Copy
Expand all Collapse all Set external action URLs. post /api/admin/config/externalactions
/api/admin/config/externalactions
Set a collection of external action URLs that are displayed in the UI.
+
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 200 Actions have been updated.
+ Request samples Content type application/json
Copy
Expand all Collapse all [ { "url" : "string" ,
"title" : "string" ,
"description" : "string" ,
"icon" : "string" ,
"color" : "string" ,
"openExternally" : true
} ]
Delete a single webhook. post /api/admin/webhooks/delete
/api/admin/webhooks/delete
Delete a single webhook by its ID.
+
Request Body schema: application/json
id string
The webhook id to delete
+
Request samples Content type application/json
Create a webhook. post /api/admin/webhooks/create
/api/admin/webhooks/create
Create a single webhook that acts on the requested events.
+
Request Body schema: application/json
url string
The url to post the events to.
+
events Array of strings
The events to be notified about.
+
Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Set moderator priviledges on a chat users. post /api/admin/chat/users/setmoderator
/api/admin/chat/users/setmoderator
Give a chat user ID and be able to grant or remove moderator priviledges to this user.
+
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 200 Operation Success/Failure Response
+ Request samples Content type application/json
{ "userId" : "xJ84_48Ghj" ,
"isModerator" : true
}
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Get a list of chat moderator users. get /api/admin/chat/users/moderators
/api/admin/chat/users/moderators
Response samples Content type application/json
Copy
Expand all Collapse all [ { "id" : "yklw5Imng" ,
"displayName" : "awesome-pizza" ,
"displayColor" : 42 ,
"createdAt" : "2019-08-24T14:15:22Z" ,
"previousNames" : "awesome-pizza,user42" ,
} ]
Get the followers of this instance Response samples Content type application/json
Copy
Expand all Collapse all Get a list of follow requests that are pending. get /api/admin/followers/pending
/api/admin/followers/pending
Get a list of follow requests that have been blocked/rejected. get /api/admin/followers/blocked
/api/admin/followers/blocked
Approve a pending follow request. post /api/admin/followers/approve
/api/admin/followers/approve
Request Body schema: application/json
actorIRI string
The requestor's remote IRI used to identify the user.
+
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. A list of names to select from randomly for new chat users. post /api/admin/config/chat/suggestedusernames
/api/admin/config/chat/suggestedusernames
Request Body schema: application/json
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Return Prometheus-compatible scraper metrics. Responses 200 Prometheus-compatible scraper values.
+
Endpoints related to the chat interface.
+
Register a chat user Register a user that returns an access token for accessing chat.
+
Request Body schema: application/json
displayName string
Optionally provide a display name you want to assign to this user when registering.
+
Request samples Content type application/json
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.
+
Response samples Content type application/json
Copy
Expand all Collapse all Get Custom Emoji Get a list of custom emoji that are supported in chat.
+
Response samples Content type application/json
Copy
Expand all Collapse all APIs built to allow 3rd parties to interact with an Owncast server.
+
Set the stream title. post /api/integrations/streamtitle
/api/integrations/streamtitle
Set the title of the currently streaming content.
+
Request Body schema: application/json
value string or integer or object or boolean
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Send a chat message. post /api/integrations/chat/send
/api/integrations/chat/send
Send a chat message on behalf of a 3rd party integration, bot or service.
+
Request Body schema: application/json
body string
The message text that will be sent as the user.
+
Request samples Content type application/json
Response samples Content type application/json
{ "success" : true ,
"message" : "sent"
}
Send a system chat message. post /api/integrations/chat/system
/api/integrations/chat/system
Send a chat message on behalf of the system/server.
+
Request Body schema: application/json
body string
The message text that will be sent as the system user.
+
Request samples Content type application/json
Response samples Content type application/json
{ "success" : true ,
"message" : "sent"
}
Send a chat action. post /api/integrations/chat/action
/api/integrations/chat/action
Send an action that took place to the chat.
+
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.
+
Request samples Content type application/json
Response samples Content type application/json
{ "success" : true ,
"message" : "sent"
}
Send system chat message to a client, identified by its ClientId post /api/integrations/chat/system/client/{clientId}
/api/integrations/chat/system/client/{clientId}
Send a chat message on behalf of the system/server to a single client.
+
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 500 Message was not sent to the client
+ Request samples Content type application/json
Response samples Content type application/json
{ "success" : true ,
"messages" : "sent"
}
Create an access token. post /api/admin/accesstokens/create
/api/admin/accesstokens/create
Create a single access token that has access to the access scopes provided.
+
Request Body schema: application/json
name string
The human-readable name to give this access token.
+
scopes
Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Delete an access token. post /api/admin/accesstokens/delete
/api/admin/accesstokens/delete
Delete a single access token.
+
Request Body schema: application/json
Request samples Content type application/json
Response samples Content type application/json
Return all access tokens. get /api/admin/accesstokens Return all of the available access tokens.
+
Responses 200 Tokens are returned
+ Response samples Content type application/json
Set external action URLs. post /api/admin/config/externalactions
/api/admin/config/externalactions
Set a collection of external action URLs that are displayed in the UI.
+
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 200 Actions have been updated.
+ Request samples Content type application/json
Copy
Expand all Collapse all [ { "url" : "string" ,
"title" : "string" ,
"description" : "string" ,
"icon" : "string" ,
"color" : "string" ,
"openExternally" : true
} ]
Return a list of currently connected clients get /api/integrations/clients
/api/integrations/clients
Return a list of currently connected clients with optional geo details.
+
Responses 200 Successful response of an array of clients
+ Response samples Content type application/json
Copy
Expand all Collapse all [ { "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" ,
"user" :
{ "id" : "yklw5Imng" ,
"displayName" : "awesome-pizza" ,
"displayColor" : 42 ,
"createdAt" : "2021-07-08T20:21:25.303402404-07:00" ,
"previousNames" : "awesome-pizza,coolPerson23"
} } ]
Historical Chat Messages get /api/integrations/chat Used to get the backlog of chat messages.
+
Response samples Content type application/json
Copy
Expand all Collapse all Update the visibility of chat messages. post /api/integrations/chat/updatemessagevisibility
/api/integrations/chat/updatemessagevisibility
Pass an array of IDs you want to change the chat visibility of.
+
Request Body schema: application/json
visible boolean
Are these messages visible.
+
idArray
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Chat-related actions that can take place by a moderator.
+
Update the visibility of chat messages. post /api/chat/updatemessagevisibility
/api/chat/updatemessagevisibility
Pass an array of IDs you want to change the chat visibility of.
+
Request Body schema: application/json
visible boolean
Are these messages visible.
+
idArray
Responses 200 Operation Success/Failure Response
+ Request samples Content type application/json
Copy
Expand all Collapse all Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Disable (block) or re-enable a chat user. post /api/chat/users/setenabled
/api/chat/users/setenabled
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 200 Operation Success/Failure Response
+ Request samples Content type application/json
{ "userId" : "string" ,
"enabled" : true
}
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Set moderator priviledges on a chat users. post /api/admin/chat/users/setmoderator
/api/admin/chat/users/setmoderator
Give a chat user ID and be able to grant or remove moderator priviledges to this user.
+
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 200 Operation Success/Failure Response
+ Request samples Content type application/json
{ "userId" : "xJ84_48Ghj" ,
"isModerator" : true
}
Response samples Content type application/json
Example Operation succeeded. Operation failed. Operation succeeded. Get a list of chat moderator users. get /api/admin/chat/users/moderators
/api/admin/chat/users/moderators
Response samples Content type application/json
Copy
Expand all Collapse all [ { "id" : "yklw5Imng" ,
"displayName" : "awesome-pizza" ,
"displayColor" : 42 ,
"createdAt" : "2019-08-24T14:15:22Z" ,
"previousNames" : "awesome-pizza,user42" ,
} ]
Information The client configuration. Information useful for the user interface.
+
Response samples Content type application/json
Copy
Expand all Collapse all { "name" : "string" ,
"summary" : "string" ,
"logo" : "string" ,
"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.
+
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.
+
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.
+
Response samples Content type application/json
Copy
Expand all Collapse all { "name" : "string" ,
"description" : "string" ,
"logo" : "string" ,
"nsfw" : true ,
"online" : true ,
"viewerCount" : 0 ,
"overallMaxViewerCount" : 0 ,
"sessionMaxViewerCount" : 0 ,
"lastConnectTime" : "2019-08-24T14:15:22Z"
}
Get the public followers of this instance Response samples Content type application/json
Copy
Expand all Collapse all Return the information needed to redirect a user to a fediverse server to perform a remote follow action. Request Body schema: application/json
Responses 200 Remote follow redirect details
+ Request samples Content type application/json
Response samples Content type application/json