Table of Contents

Modules - Owncast API

Integration API (ctx.owncast_client)

Client Construction
Chat Sending
Chat Moderation and Queries
Server Status and Stream Title
OwncastError

Admin API (ctx.admin_client)

Client Construction
Auth and Access Tokens
Read-Only Endpoints
Chat and Users
IP Bans
Chat Config
Server Identity and Appearance
Video
Server Infrastructure
Federation
Notifications and Webhooks
Emoji, Directory, and YP
Prometheus Metrics
Helper Dataclasses

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.

Built-in Modules

Creating New Modules

Modules - Owncast API

Integration API (ctx.owncast_client)

Client Construction

Chat Sending

Chat Moderation and Queries

Server Status and Stream Title

OwncastError

Admin API (ctx.admin_client)

Client Construction

Auth and Access Tokens

Read-Only Endpoints

Chat and Users

IP Bans

Chat Config

Server Identity and Appearance

Video

Server Infrastructure

Federation

Notifications and Webhooks

Emoji, Directory, and YP

Prometheus Metrics

Helper Dataclasses

Integration API (`ctx.owncast_client`)

Admin API (`ctx.admin_client`)