Updated Owncast API module docs for v0.2.5 client surface and bumped prerequisite version.
+1
-1
@@ -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
|
||||
|
||||
+116
-92
@@ -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. |
|
||||
| `get_connected_clients()` | Get currently connected viewers. |
|
||||
| `set_stream_title(title)` | Update the stream title. |
|
||||
|
||||
### 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. |
|
||||
|
||||
### Stream Control
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `set_stream_title(title)` | Set the stream title. |
|
||||
| `get_playback_metrics()` | Video playback metrics. |
|
||||
| `get_connected_chat_clients()` | Connected chat clients. |
|
||||
| `disconnect_stream()` | Disconnect the current inbound stream. |
|
||||
|
||||
### Chat Management
|
||||
### Chat and Users
|
||||
|
||||
| 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). |
|
||||
| `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. |
|
||||
|
||||
### 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_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. |
|
||||
| `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
|
||||
|
||||
@@ -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
|
||||
|
||||
| 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)
|
||||
### 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. |
|
||||
|
||||
### 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)
|
||||
### Federation
|
||||
|
||||
| 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. |
|
||||
| `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. |
|
||||
| `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
|
||||
|
||||
@@ -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. |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user