Report this server's runtime configuration and health without revealing secrets. Shows the API base URLs, whether a default token is set (boolean only), registry location and counts, and the HTTP timeout.

Args: response_format. Returns { server, version, apiBase, datastreamBase, defaultAppTokenConfigured, registryPath, registeredApps, registeredDataStreams, rundownTemplates, httpTimeoutMs }.

Get an app instance's metadata: numeric ids, name, folder, linked composition id, thumbnail preview URL, live output URLs, and the derived control/command/model API URLs.

Args: app (alias) or appToken; response_format. Returns { id, name, accountId, compositionId, folder, thumbnail, outputUrl, broadcastOutputUrl, ...URLs }. Use this to confirm a token points at the intended app and to grab a preview/output URL.

Get the structural model of an app: every sub-composition and its control nodes with id, title, type (lowercase: text, textarea, number, image, color, checkbox, audio, json, timecontrol, button), default/reset values, and index. This is the schema-discovery call to run BEFORE writing content — payload keys must be control-node ids from here.

Args: app/appToken; sub_composition (optional name/id filter); response_format. Returns { subCompositions: [{ id, name, state, nodeCount, nodes: [{ id, title, type, index, defaultValue, resetValue }] }] }.

Get the current on-air/staged state per sub-composition: its animation state (In/Out/Out1/Out2) and the current payload values keyed by control-node id. Use to see what is live right now.

Args: app/appToken; response_format. Returns { entries: [{ subCompositionId, subCompositionName, state, mainComposition, payload }] }.

Convenience read that joins the model (structure + types) with the live control state (current values) by sub-composition id — one flat view per sub-composition with each node's id, title, type, and current value. The best single call to understand "what can I fill and what's in it now".

Args: app/appToken; response_format. Returns { subCompositions: [{ id, name, state, nodes: [{ id, title, type, currentValue, defaultValue, resetValue }] }] }.

Search all control nodes across the app's compositions, filtered by type and/or title substring. E.g. type='image' locates every fillable image node (the common newsroom case), type='text' for headlines. Saves hand-parsing the model tree.

Args: app/appToken; type (optional, e.g. 'image'); title_contains (optional); response_format. Returns { count, nodes: [{ subCompositionId, subCompositionName, id, title, type }] }.

Fill control nodes of one or more sub-compositions in a single PATCH. Each update targets a sub-composition (by name or id) and supplies a payload mapping control-node ids → values.

Value formats by node type: text/textarea→string, number→number, image/audio→URL string, color→{r,g,b,a} (0–255) or hex string, checkbox→boolean, selection→option value, json→object. Node ids come from get_model / find_nodes.

Batching multiple sub-compositions here (rather than many calls) conserves rate limit. This sets content only — it does NOT animate; use animate_state or update_and_animate to take on/off air.

Args: app/appToken; updates: [{ subCompositionName | subCompositionId, payload }]; response_format. Returns { success, updatedCount }.

Set an image-type control node to a hosted image URL (the only way to place imagery — Singular has no upload API, so the asset must already be reachable at a public URL). Validates that the target node is type 'image' (via get_model) and, by default, that the URL is reachable and looks like an image before sending.

Args: app/appToken; subCompositionName | subCompositionId; nodeId (the image node's id) OR nodeTitle (matched from the model); imageUrl; validate_url (default true); force (default false — set true to send even if validation fails); response_format. Returns { success, subComposition, nodeId, imageUrl, urlCheck }.

Clear/reset content by writing each targeted node back to its resetValue (from the model). Target specific nodeIds, or omit them to reset every node in the sub-composition — handy to blank a template between stories/segments. This changes on-air content if the sub-composition is live.

Args: app/appToken; subCompositionName | subCompositionId; nodeIds (optional — default all nodes in the sub-composition); response_format. Returns { success, subComposition, resetCount, nodeIds }.

Trigger animation state transitions to take sub-compositions on or off air. Accepts multiple targets for a coordinated transition in one call. This does NOT change content — combine with update_content first, or use update_and_animate to do both atomically.

Args: app/appToken; targets: [{ subCompositionName | subCompositionId, state: In|Out|Out1|Out2 }]; response_format. Returns { success, count }.

Atomically set a sub-composition's payload AND its animation state in a single PATCH, so the template is filled and taken to air together (avoids a flash of stale content that a separate fill-then-animate can cause).

Args: app/appToken; subCompositionName | subCompositionId; payload (control-node id → value); state (In|Out|Out1|Out2); response_format. Returns { success, subComposition, state }.

Animate every overlay in the control app to its Out state — the 'clear the screen' / segment-end / panic control. Uses POST /command { action: 'TakeOutAllOutput' } (the only documented command action).

Args: app/appToken; response_format. Returns { success }.

Store a data stream's PRIVATE token under an alias so push_datastream can reference it by name (the raw token is never echoed back). Create the stream and get its private token from the Dashboard → Data Stream Manager.

Args: alias; privateToken; response_format. Returns { alias }.

List the aliases of data streams registered on this server (no tokens). Args: response_format. Returns { count, dataStreams: [{ alias, addedAt }] }.

PUT a JSON payload to a data stream for sub-300ms delivery into any composition linked to it (scores, clocks, live stats) — bypasses the control API's per-minute rate limits. The payload shape must match what the linked sub-composition expects (configured in the Dashboard). Hard limit: 60 KB per package.

Args: stream (alias) or privateToken; data (JSON object); response_format. Returns { success, bytes }.

Return the app instance's live output URL, broadcast output URL, and auto-generated thumbnail preview URL (from metadata). Hand these to a human or a browser renderer to see what's on air. Note: Singular renders client-side; there is no server-side frame/snapshot render API.

Args: app/appToken; response_format. Returns { outputUrl, broadcastOutputUrl, thumbnail, name }.

Check that an image URL is well-formed, reachable, and looks like an image (by Content-Type or extension) before using it in set_image. Useful for pre-flighting rundown graphics.

Args: imageUrl; response_format. Returns { ok, status, contentType, reason }.

Store a Singular app token under a friendly alias so later tools reference the app by alias (the raw token is never returned to the model). By default verifies the token by fetching metadata and uses the app's real name.

Args: alias; token; name (optional); verify (default true); response_format. Returns { alias, name, verified }.

List app aliases registered on this server (names + when added; never tokens). Args: response_format. Returns { count, apps: [{ alias, name, addedAt }] }.

Delete an app alias (and its stored token) from the registry. Args: alias; response_format. Returns { alias, removed }.

Bind a rundown item type (e.g. 'lower-third', 'ots', 'full-frame', 'ticker') to a specific app + sub-composition, plus a field map from story field names → control-node ids. Used by prepare_item and play_rundown_item. By default validates the sub-composition and node ids against the live model.

Args: name; appAlias; subCompositionName | subCompositionId; fieldMap (storyField → nodeId); validate (default true); response_format. Returns { name, appAlias, subComposition, fieldCount, validation }.

List mapped rundown templates with their app, sub-composition, and field maps. Args: response_format. Returns { count, templates: [...] }.

Resolve a rundown item against its template WITHOUT sending anything: maps story fields to control-node ids, validates them against the live model, and returns exactly the payload that play_rundown_item would send. Use to preview/verify before air.

Args: template (name); fields (storyField → value); response_format. Returns { template, subComposition, payload, unmappedFields, missingNodes, wouldSend }.

Resolve a rundown item from its template and take it to air: fills the mapped payload and animates the sub-composition In, atomically. Optionally schedules an automatic Out after auto_out_ms (server-side, in-memory — does not survive a restart).

Args: template (name); fields (storyField → value); auto_out_ms (optional); response_format. Returns { template, subComposition, sentPayload, state, autoOutMs, unmappedFields, missingNodes }.

Poll the live control state and report which sub-compositions are currently In (on air) vs Out, plus what changed since the last poll of this app (Singular has no webhooks, so polling is the only awareness mechanism).

Args: app/appToken; response_format. Returns { onAir: [...], offAir: [...], changed: [{ subComposition, from, to }] }.