API

The PX Studio API lets your own scripts, Streamer.bot actions or tools create overlays, place widgets, switch scenes and fire alerts. It uses the same permission checks as the editor.

Personal tokens

1. Open Settings → API & AI apps and click New token.

2. Give it a name, choose the permissions (scopes) and an expiry: 7, 30, 90 or 365 days, or never.

3. Copy the token. It starts with pxp_ and is shown only once.

Revoking a token works immediately. Creation and revocation are listed in the log on the same tab.

First requests

export PX=https://pxstudio.cloud/api/v1 TOKEN=pxp_YOUR_TOKEN
curl -s -H "Authorization: Bearer $TOKEN" $PX/me
curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"name":"Neon Show","preset":"look-neon"}' $PX/overlays

Add a text widget to an overlay:

curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"widget":"element-text","values":{"text":"Be right back"},"layout":{"x":0,"y":-200,"scale":1}}' $PX/overlays/OVERLAY_ID/members

Upload a file as raw bytes (no multipart):

curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: video/mp4' --data-binary @loop.mp4 "$PX/uploads?name=loop.mp4"

Layout units

Positions are in design pixels of a 1920 wide canvas. x and y count from the center of the canvas, y grows downwards. scale goes from 0.05 to 4, rot is in degrees and opacity from 0 to 1.

Safe concurrent edits

• Send expectedRev when you change layers and expectedVersion when you change settings. If someone changed the overlay in the meantime, you get 409 with the current state in details.
• Send an Idempotency-Key header (8 to 200 characters) when you create overlays, scenes or layers. Retrying with the same key returns the first answer for 24 hours. While the first request is still running, a retry gets 409 (idempotency_in_progress); try again a moment later.

Limits and errors

The API allows 300 requests per minute per account; frequent overlay changes can be limited further. A 429 answer carries Retry-After. Common error codes: not_found, insufficient_scope, invalid_request, rev_conflict, field_conflict and rate_limited. update_member_fields lists setting keys the widget does not have as ignored; if none of the keys is known, the answer is 400 unknown_field. update_member_fields and add_member check every value before saving: a dropdown takes the option key (miami), not the label. An unknown option answers 422 invalid_option with the allowed options, a wrong type answers 422 invalid_value, and nothing is saved. get_member_fields lists dropdown options in dropdowns.

API reference

Every one of the 203 operations has its own entry with parameters, scope and a curl example:

The machine-readable version is the OpenAPI file↗. An overview by area:

• Overlays (including duplicate_overlay), scenes (including duplicate_scene, reorder_scenes, go_live_scene and take_preview_to_program) and the overlay history (list_history, restore_history).
• Layers (add_member, update_member, update_members, duplicate_member, remove_member), layer groups (create_group, update_group, set_group_layers, move_group, delete_group, duplicate_group) and widget settings.
• Live control: fire_member_command, send_test_alert, deck buttons (list_deck_macros, fire_deck_macro), media favorites (list_media_favorites, show_media, hide_media), stream activity (list_activity, replay_activity_event), stream info (get_stream_info, set_stream_info) and get_output_status.
• The widget catalog, presets, uploads (list_uploads, upload_file, rename_upload, delete_upload), the last stream report, bot commands and song requests (get_song_queue, control_songs, set_song_volume, remove_song_request, clear_song_queue).

The same operations are available as tools in the MCP server. Every tool that deletes without undo (DESTRUCTIVE), shows something on air (ON AIR), posts publicly (PUBLIC), acts on viewers or chat modes (MODERATION) or calls an outside service (EXTERNAL) asks the AI app for your explicit OK there: it only runs with confirm: true.

Studio operations

• Automations (automations:read, automations:write): list_automations, get_automation_options, list_automation_activity, create_automation, update_automation, set_automation_enabled, delete_automation, list_action_webhooks, delete_action_webhook. Targets are layers as overlayId and memberId. Discord webhook URLs and action webhook links are never shown in answers; existing Discord rules keep their URL when you change them, and new Discord rules or action webhooks are created in the app (the API answers ui_only).
• Organize: spots (list_spots, create_spot, update_spot, apply_spot, delete_spot), saved positions (set_position_presets, apply_position_preset), deck buttons (create_deck_macro, update_deck_macro, reorder_deck_macros, delete_deck_macro, get_deck_favorites, set_deck_favorites), notes with comments and reactions, restore_look_scenes, list_templates, add_linked_member and the OBS scene sync mappings (set_obs_scene_mapping is ON AIR: OBS later switches your live scene by itself).
• Live: media favorites, browse_media (GIFs, stickers and memes), share_media, move_media, clear_drawing, viewer drawing (get_viewer_drawing, moderate_viewer_drawing), get_activity_stats and get_member_live_data.
• Account and packs: get_channel_info and set_channel_info for Twitch and Kick, search_stream_categories, stream sessions, daily stats, account activity, studio home, play recommendations, get_account_overview (no email address), premium overlays, packs (list_packs, get_pack, set_pack_theme) and the marketplace catalog. set_pack_theme deep-merges: send only the values to change at their path (for example {"look": {"accent": "#ff5c39"}}), null removes a value, lists replace the whole list. Values that could be secret show as "[hidden]" and cannot be set.

Shared overlays work with exactly your team permissions. Answers never contain your OBS link, share or pack links, webhook URLs or email addresses.

Every operation runs with exactly your rights in the editor. Widgets are addressed as a layer (overlayId plus memberId).

PXStudioBot, community, YouTube player and chat

• Bot (bot:read, bot:write): status per platform (get_bot_status), joining or leaving your chat (set_bot_platform_active), bot language (set_bot_language), settings and built-in messages (get_bot_settings, update_bot_settings, get_bot_system_messages, update_bot_system_messages), built-in commands on or off (set_builtin_command_enabled), commands with every field of the bot editor (create_bot_command, update_bot_command, set_bot_command_enabled, export_bot_commands, import_bot_commands, replace_bot_commands), timers, counters, quotes, custom APIs, moderation filters and song request rules (update_song_settings, move_song_request).
• Community (bot:read, bot:write): giveaways (get_giveaway, start_giveaway, draw_giveaway_winner, control_giveaway, remove_giveaway_entry, cancel_giveaway, defaults and history), loyalty points (settings, leaderboard, one viewer, rewards, adjust_loyalty_points) and Twitch channel point actions.
• YouTube player (overlays:read, actions:fire): get_youtube_queue, play_youtube_video, queue_youtube_video, control_youtube, move_youtube_video, remove_youtube_video, clear_youtube_queue. Videos are 11 character video ids.
• Chat (overlays:read, chat:write, chat:moderate): get_chat_capabilities, send_chat_message (Twitch, Kick and YouTube; YouTube only while the stream is live), moderate_chat, get_chat_mode, set_chat_mode. You act with your own platform connection in the overlay owner's chat; the platform decides whether a moderation lands.
• control_giveaway rerolls the last winner, or with login exactly that winner. adjust_loyalty_points takes an optional reason, which a team member's change keeps in the owner's team activity.

Bot operations take an optional overlayId query parameter: with it you act on the bot of the owner of an overlay shared with you, with the same rights as in the editor (design for settings, trigger widgets for live actions). Without it they act on your own bot. Joining a chat, the bot language and channel point actions are only for your own account.

Actions of commands, rewards and channel point actions point to a layer (overlayId plus memberId), a scene or a spot. An exported command whose layer you cannot see carries actionTarget: { unattached: true }; importing it keeps the saved action of the command with that name. Discord webhook actions are not available through the API.

Custom API header values are only set in the Bot desk; lists never show header values, URL keys or token-like parts of the address. Changing a custom API to another host removes its saved header values: such a change answers ui_only unless you send dropHeaders: true to confirm. Viewers appear only with login, display name and platform.