Updated Owncast API module docs for v0.2.5 client surface and bumped prerequisite version.

Home.md

@@ -25,7 +25,7 @@ Owlbot's core is a framework for building and running modules. If the included m
 ### Prerequisites
 
 - **[uv](https://docs.astral.sh/uv/getting-started/installation/)** — handles Python and dependency management automatically
-- A running **Owncast 0.2.4** instance
+- A running **Owncast 0.2.5** instance
 - **[ffmpeg](https://ffmpeg.org/)** *(optional)* — required by the clips module for video processing. If not installed, the clips module will not load but all other modules will work normally.
 
 ### 1. Installation

Modules-Owncast-API.md

@@ -6,7 +6,13 @@ Two clients are available for talking to Owncast: the **Integration API client**
 
 This is always available. It uses Bearer token authentication (the `access_token` from config) and covers the endpoints most modules need.
 
-### Sending Messages
+### 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.
 
@@ -30,7 +36,15 @@ await ctx.owncast_client.send_system_message_to_client(
 await ctx.owncast_client.send_message("<b>bold html</b>", unsanitized=True)
 ```
 
-### Moderation
+| 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
 
 ```python
 # Hide or show messages:
@@ -38,9 +52,28 @@ 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.
 ```
 
-### Stream Info
+| 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
 
 ```python
 # Get public server status:
@@ -51,32 +84,10 @@ status = await ctx.owncast_client.get_status()
 await ctx.owncast_client.set_stream_title("Playing Minecraft")
 ```
 
-### Chat and Clients
-
-```python
-# 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, *, 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`. |
-| `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. |
+| `set_stream_title(title)` | Update the stream title. |
-| `get_connected_clients()` | Get currently connected viewers. |
 
 ### OwncastError
 
@@ -118,7 +129,22 @@ if ctx.admin_client is None:
 
 Admin API methods raise `OwncastError` on failure, same as the integration client.
 
-### Status and Monitoring
+### 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 |
 |--------|-------------|
@@ -129,31 +155,43 @@ Admin API methods raise `OwncastError` on failure, same as the integration clien
 | `get_server_config()` | Full server configuration dict. |
 | `get_logs()` | Server logs. |
 | `get_warnings()` | Server warning logs. |
-| `get_playback_metrics()` | Video playback quality metrics. |
+| `get_playback_metrics()` | Video playback metrics. |
-
+| `get_connected_chat_clients()` | Connected chat clients. |
-### Stream Control
-
-| Method | Description |
-|--------|-------------|
-| `set_stream_title(title)` | Set the stream title. |
 | `disconnect_stream()` | Disconnect the current inbound stream. |
 
-### Chat Management
+### Chat and Users
 
 | Method | Description |
 |--------|-------------|
-| `get_chat_messages()` | Chat messages (admin perspective). |
+| `get_chat_messages()` | All chat messages, unfiltered (admin view). |
-| `get_connected_chat_clients()` | Connected chat clients. |
+| `set_message_visibility(message_ids, visible)` | Hide or show messages (admin endpoint). |
-| `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. |
+
+### 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. |
 
-### Server Configuration
+### 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 |
 |--------|-------------|
@@ -163,31 +201,19 @@ Admin API methods raise `OwncastError` on failure, same as the integration clien
 | `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_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_socket_host_override(host)` | Set WebSocket host override. |
+| `set_external_actions(actions)` | Set player action buttons (list of `ExternalAction`). |
-| `set_rtmp_port(port)` | Set the RTMP server port. |
+| `set_logo(base64_data_url)` | Set the server logo from a data URL. |
-| `set_web_server_port(port)` | Set the web server port. |
+| `set_favicon(base64_data_url)` | Set a custom favicon from a base64 data URL (PNG or ICO, max 200 KB). |
-| `set_web_server_ip(ip)` | Set the web server bind IP. |
+| `reset_favicon()` | Reset the favicon to the Owncast default. |
-| `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
 
@@ -198,29 +224,19 @@ Admin API methods raise `OwncastError` on failure, same as the integration clien
 | `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. |
 
-### Social and External Actions
+### Server Infrastructure
-
-| 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_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. |
 
-### Notifications
+### Federation
-
-| 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 |
 |--------|-------------|
@@ -228,35 +244,44 @@ Admin API methods raise `OwncastError` on failure, same as the integration clien
 | `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. |
+| `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. |
 
-### Emoji
+### 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. |
 
-### Webhooks and Tokens
+### 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_webhooks()` | List all registered webhooks. |
+| `get_prometheus_metrics()` | Fetch metrics as raw Prometheus exposition text. |
-| `create_webhook(url, events)` | Create a new webhook subscription. |
+| `post_prometheus(data=None)` | POST through to the Prometheus endpoint. |
-| `delete_webhook(webhook_id)` | Delete a webhook. |
+| `put_prometheus(data=None)` | PUT through to the Prometheus endpoint. |
-| `get_access_tokens()` | List all access tokens. |
+| `delete_prometheus()` | DELETE through to the Prometheus endpoint. |
-| `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
 
@@ -299,4 +324,3 @@ Some admin methods accept dataclasses for structured input.
 | `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. |
-