Modules Owncast API

Modules - Owncast API

Two clients are available for talking to Owncast: the Integration API client (ctx.owncast_client) for everyday operations like sending messages, and the Admin API client (ctx.admin_client) for privileged server management.

Integration API (ctx.owncast_client)

This is always available. It uses Bearer token authentication (the access_token from config) and covers the endpoints most modules need.

Client Construction

Property	Description
base_url	The Owncast server base URL.

Chat Sending

All message-sending methods HTML-escape the body by default to prevent injection when echoing user-originated content. Markdown syntax is unaffected by escaping and will be rendered normally by Owncast. Pass unsanitized=True to send raw HTML intentionally.

# Regular chat message (visible to everyone):
await ctx.owncast_client.send_message("Hello, chat!")

# System message (styled differently, typically italicized/dimmed):
await ctx.owncast_client.send_system_message("Stream starting in 5 minutes.")

# Action message (like IRC /me, e.g. "BotName does something"):
await ctx.owncast_client.send_action("waves at the audience")

# Private system message (visible only to one client):
await ctx.owncast_client.send_system_message_to_client(
    client_id=event.client_id,
    body="Only this client can see this."
)

# Send raw HTML (opt out of escaping):
await ctx.owncast_client.send_message("<b>bold html</b>", unsanitized=True)

Method	Description
send_message(body, *, unsanitized=False)	Send a chat message visible to all. Body is HTML-escaped unless unsanitized=True.
send_system_message(body, *, unsanitized=False)	Send a system message visible to all. Body is HTML-escaped unless unsanitized=True.
send_action(body, *, unsanitized=False)	Send an action message (like IRC /me). Body is HTML-escaped unless unsanitized=True.
send_system_message_to_client(client_id, body, *, unsanitized=False)	Send a private system message to one client. Body is HTML-escaped unless unsanitized=True.
send_user_message()	Deprecated by Owncast (always returns HTTP 400). Use send_message instead.

Chat Moderation and Queries

# Hide or show messages:
await ctx.owncast_client.set_message_visibility(
    message_ids=["msg-id-1", "msg-id-2"],
    visible=False,  # True to show, False to hide
)

# Get details for a chat user:
details = await ctx.owncast_client.get_user_details(user_id="user-uuid")
# Returns dict with user, connectedClients, and messages.

# Recent chat history:
messages = await ctx.owncast_client.get_chat_history()
# Returns list of message dicts with user info and content.

# Currently connected viewers:
clients = await ctx.owncast_client.get_connected_clients()
# Returns list of client dicts with user info and connection details.

Method	Description
set_message_visibility(message_ids, visible)	Hide or show messages.
get_user_details(user_id)	Get details for a chat user (user info, connected clients, recent messages).
get_chat_history()	Get recent chat messages.
get_connected_clients()	Get currently connected viewers.

Server Status and Stream Title

# Get public server status:
status = await ctx.owncast_client.get_status()
# Returns dict with versionNumber, online, viewerCount, etc.

# Set the stream title:
await ctx.owncast_client.set_stream_title("Playing Minecraft")

Method	Description
get_status()	Get public server status dict.
set_stream_title(title)	Update the stream title.

OwncastError

All methods raise OwncastError on failure:

from owlbot.api import OwncastError

try:
    await ctx.owncast_client.send_message("Hello!")
except OwncastError as e:
    ctx.logger.error(f"Owncast API error {e.status}: {e.message}")

Attribute	Type	Description
status	int	HTTP status code, or 0 for connection errors.
message	str	Error message from the server (or connection error string).

Admin API (ctx.admin_client)

The admin client is only available when enabled in config:

owncast:
  admin:
    enabled: true
    username: "admin"
    password: "your-password"

If not enabled, ctx.admin_client is None. Always check before using it:

if ctx.admin_client is None:
    ctx.logger.warning("Admin API not enabled")
    return

Admin API methods raise OwncastError on failure, same as the integration client.

Client Construction

Property	Description
base_url	The Owncast server base URL.

Auth and Access Tokens

Method	Description
set_admin_password(password)	Change the admin password.
get_access_tokens()	List all access tokens.
create_access_token(name, scopes)	Create a new access token.
delete_access_token(token)	Delete an access token.

Read-Only Endpoints

Method	Description
get_status()	Server status including stream info and viewer count (admin view).
get_active_viewers()	List of currently active viewers.
get_viewers_over_time(window_start)	Viewer count data for charting (window_start is a Unix timestamp).
get_hardware_stats()	Server hardware stats (CPU, memory, disk).
get_server_config()	Full server configuration dict.
get_logs()	Server logs.
get_warnings()	Server warning logs.
get_playback_metrics()	Video playback metrics.
get_connected_chat_clients()	Connected chat clients.
disconnect_stream()	Disconnect the current inbound stream.

Chat and Users

Method	Description
get_chat_messages()	All chat messages, unfiltered (admin view).
set_message_visibility(message_ids, visible)	Hide or show messages (admin endpoint).
set_user_enabled(user_id, enabled)	Enable or disable a chat user.
get_disabled_users()	List disabled users.
set_user_moderator(user_id, is_mod)	Grant or revoke moderator status.
get_moderators()	List moderator users.

IP Bans

Method	Description
ban_ip_address(ip)	Ban an IP address.
unban_ip_address(ip)	Remove an IP ban.
get_ip_address_bans()	List banned IPs.

Chat Config

Method	Description
set_chat_disabled(disabled)	Enable or disable chat.
set_chat_join_messages_enabled(enabled)	Show or hide join messages.
set_chat_established_mode(enabled)	Enable or disable established user mode.
set_chat_spam_protection(enabled)	Enable or disable spam protection.
set_chat_slur_filter(enabled)	Enable or disable the slur filter.
set_chat_require_authentication(required)	Require users to authenticate before sending messages.
set_forbidden_usernames(names)	Set list of forbidden usernames.
set_suggested_usernames(names)	Set list of suggested usernames.

Server Identity and Appearance

Method	Description
set_server_name(name)	Set the server name.
set_server_summary(summary)	Set the server summary.
set_welcome_message(message)	Set the welcome message for new viewers.
set_offline_message(message)	Set the offline stream message.
set_page_content(content)	Set custom page content (HTML/markdown).
set_server_url(url)	Set the public server URL.
set_tags(tags)	Set server tags (list of strings).
set_nsfw(nsfw)	Set the NSFW flag.
set_social_handles(handles)	Set social media links (list of SocialHandle).
set_stream_title(title)	Set the stream title.
set_custom_styles(css)	Set custom CSS.
set_custom_javascript(js)	Set custom JavaScript.
set_color_variables(variables)	Set custom color variables.
set_hide_viewer_count(hide)	Show or hide viewer count.
set_disable_search_indexing(disabled)	Enable or disable search indexing.
set_external_actions(actions)	Set player action buttons (list of ExternalAction).
set_logo(base64_data_url)	Set the server logo from a data URL.
set_favicon(base64_data_url)	Set a custom favicon from a base64 data URL (PNG or ICO, max 200 KB).
reset_favicon()	Reset the favicon to the Owncast default.

Video

Method	Description
set_video_codec(codec)	Set the video codec.
set_video_variants(variants)	Set output quality levels (list of VideoVariant).
set_video_serving_endpoint(endpoint)	Set CDN endpoint for video.
set_stream_latency(level)	Set stream latency level.
set_stream_keys(keys)	Set stream keys (list of StreamKey).
set_ffmpeg_path(path)	Set the path to the ffmpeg binary.

Server Infrastructure

Method	Description
set_socket_host_override(host)	Set WebSocket host override.
set_rtmp_port(port)	Set the RTMP server port.
set_web_server_port(port)	Set the web server port.
set_web_server_ip(ip)	Set the web server bind IP.
set_s3_config(enabled, endpoint, access_key, secret, bucket, region)	Configure S3 storage.

Federation

Method	Description
set_federation_enabled(enabled)	Enable or disable federation.
set_federation_username(name)	Set the federation username.
set_federation_go_live_message(message)	Set the go-live notification for followers.
set_federation_blocked_domains(domains)	Set blocked federation domains.
set_federation_activity_private(private)	Mark activity as private (followers-only).
set_federation_show_engagement(enabled)	Show or hide likes and boosts in chat.
send_federated_message(message)	Send a public message to the Fediverse from the server's account.
get_followers(offset, limit)	Get paginated follower list.
get_pending_follow_requests()	Get pending follow requests.
get_blocked_followers()	Get blocked followers.
get_federated_actions(offset, limit)	Get paginated list of federated activities.
approve_follower(actor_iri, approved)	Approve or reject a follow request.

Notifications and Webhooks

Method	Description
set_discord_notifications(enabled, webhook, go_live_message)	Configure Discord notifications.
set_browser_notifications(enabled, go_live_message)	Configure browser notifications.
get_webhooks()	List all registered webhooks.
create_webhook(url, events)	Create a new webhook subscription.
delete_webhook(webhook_id)	Delete a webhook.

Emoji, Directory, and YP

Method	Description
upload_emoji(name, data_base64)	Upload a custom emoji (base64 image data).
delete_emoji(name)	Delete a custom emoji.
set_directory_enabled(enabled)	Enable or disable Owncast directory listing.
reset_yp_registration()	Clear the Owncast directory registration key.

Prometheus Metrics

The Owncast admin API exposes a proxy to the Prometheus metrics endpoint. These methods are thin wrappers for that proxy.

Method	Description
get_prometheus_metrics()	Fetch metrics as raw Prometheus exposition text.
post_prometheus(data=None)	POST through to the Prometheus endpoint.
put_prometheus(data=None)	PUT through to the Prometheus endpoint.
delete_prometheus()	DELETE through to the Prometheus endpoint.

Helper Dataclasses

Some admin methods accept dataclasses for structured input.

StreamKey

Field	Type	Description
key	str	The stream key string.
comment	str	A human-readable label (e.g., "OBS - Main PC").

VideoVariant

Field	Type	Description
name	str	Display name for this variant (e.g., "720p").
video_bitrate	int	Video bitrate in kbps.
audio_bitrate	int	Audio bitrate in kbps.
scaled_width	int	Output width in pixels.
scaled_height	int	Output height in pixels.
framerate	int	Output framerate.
cpu_usage_level	int	CPU usage level (1-5, higher = better quality).
is_audio_passthrough	bool	Whether to pass audio through without re-encoding.
is_video_passthrough	bool	Whether to pass video through without re-encoding.

SocialHandle

Field	Type	Description
platform	str	Platform name (e.g., "twitter", "discord").
url	str	URL to the social profile or invite.

ExternalAction

Field	Type	Description
url	str	The URL the button links to.
title	str	Button label text.
description	str	Tooltip or description of the action.
icon	str	URL to an icon image.
open_externally	bool	Whether to open in a new tab instead of an iframe.