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.

Sending Messages

# 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."
)

Moderation

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

Stream Info

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

Chat and Clients

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

Full Method Reference

Method	Description
base_url	Property: the Owncast server base URL.
send_message(body)	Send a chat message visible to all.
send_system_message(body)	Send a system message visible to all.
send_action(body)	Send an action message (like IRC /me).
send_system_message_to_client(client_id, body)	Send a private system message to one client.
set_message_visibility(message_ids, visible)	Hide or show messages.
set_stream_title(title)	Update the stream title.
get_status()	Get public server status dict.
get_chat_history()	Get recent chat messages.
get_connected_clients()	Get currently connected viewers.

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

The admin client extends OwncastClient (so it inherits all the integration methods) and adds admin-only endpoints using HTTP Basic Auth. It also raises OwncastError on failure.

Status and Monitoring

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 quality metrics.

Stream Control

Method	Description
set_stream_title(title)	Set the stream title.
disconnect_stream()	Disconnect the current inbound stream.

Chat Management

Method	Description
get_chat_messages()	Chat messages (admin perspective).
get_connected_chat_clients()	Connected chat clients.
set_message_visibility(message_ids, visible)	Hide/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.
ban_ip_address(ip)	Ban an IP address.
unban_ip_address(ip)	Remove an IP ban.
get_ip_address_bans()	List banned IPs.

Server Configuration

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_admin_password(password)	Change the admin password.
set_custom_styles(css)	Set custom CSS.
set_custom_javascript(js)	Set custom JavaScript.
set_tags(tags)	Set server tags (list of strings).
set_nsfw(nsfw)	Set the NSFW flag.
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_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_ffmpeg_path(path)	Set the path to the ffmpeg binary.

Chat Settings

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_forbidden_usernames(names)	Set list of forbidden usernames.
set_suggested_usernames(names)	Set list of suggested usernames.

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

Social and External Actions

Method	Description
set_social_handles(handles)	Set social media links (list of SocialHandle).
set_external_actions(actions)	Set player action buttons (list of ExternalAction).
set_directory_enabled(enabled)	Enable or disable Owncast directory listing.

Storage (S3)

Method	Description
set_s3_config(enabled, endpoint, access_key, secret, bucket, region)	Configure S3 storage.

Notifications

Method	Description
set_discord_notifications(enabled, webhook, go_live_message)	Configure Discord notifications.
set_browser_notifications(enabled, go_live_message)	Configure browser notifications.

Federation (ActivityPub)

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.
send_federated_message(message)	Send a message to all followers.
get_followers(offset, limit)	Get paginated follower list.
get_pending_follow_requests()	Get pending follow requests.
get_blocked_followers()	Get blocked followers.
approve_follower(actor_iri, approved)	Approve or reject a follow request.

Emoji

Method	Description
upload_emoji(name, data_base64)	Upload a custom emoji (base64 image data).
delete_emoji(name)	Delete a custom emoji.

Webhooks and Tokens

Method	Description
get_webhooks()	List all registered webhooks.
create_webhook(url, events)	Create a new webhook subscription.
delete_webhook(webhook_id)	Delete a webhook.
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.

Logo

Method	Description
set_logo(base64_data_url)	Set the server logo from a data URL.

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.