Orisu

WHAT — Returns the actual input + output ports a node exposes for a given config, including dynamic-arity expansion, PLUS its full config-field schema: config_fields (authored key/label/type/default/options), config_defaults, schema_fields (every Zod-derived config key with type/enum/min/max/description), and — for model-bound nodes (generate_image, generate_video, ...) — capability_kind and models[] (every compatible model id + that model's own aspect_ratio/quality/resolution option lists). Each input port also carries its fan-out/arity flags: accepts_array (this port fans out over an upstream ARRAY — the downstream subgraph runs once per item), loop_mode (loop-eligible), multiple (accepts multiple incoming edges), and expand_key/dynamic for config-driven port counts. WHEN — Call this BEFORE wiring edges to any node whose ports depend on config (prompt_concatenator, list_selector, router), AND whenever you need to know whether a port fans out over an array (accepts_array). ALSO call this before setting ANY node's config — it's the single call that answers both 'what ports does this node have' and 'what config keys/models/options are valid', so you never have to guess a field name (brand_context's companyName, human_review's instructions, etc.) or a model's aspect ratio. Skipping this is the #1 reason graphs fail semantic validation. NEXT — Use the returned port ids in your GraphSpec edges (sourcePort / targetPort). A port with accepts_array will map a single node over an upstream array. Use config_fields/schema_fields keys (camelCase) for config, and for model-bound nodes pick config.model from models[] then a value from that model's own fields[].options. Then call validate_graph to confirm the wiring works. PITFALLS — Pass the EXACT config you intend to commit — different `elements` count produces different port lists. models[] excludes deprecated variants. For a bird's-eye view across many node types at once, orisu://nodes (catalog) and orisu://nodes/{type} (single-node) carry the identical config schema and are cheaper to read in bulk.

get_effective_ports

WHAT — Returns the exact { node_id, value_type, example } per input-node in the agent's latest graph. The `inputs` map you pass to trigger_run keys off these node_ids; each value should match the value_type (string for text_prompt; { url, key, contentType, size, name } for upload_*). WHEN — Call BEFORE trigger_run / trigger_app for any agent whose inputs you haven't seen before. Cheap (one DB read), saves you a round-trip when trigger_run rejects with VALIDATION_FAILED because the shape was wrong. NEXT — Build trigger_run's inputs arg as { [node_id]: value } using the returned shapes — text_prompt nodes take a string, upload_* nodes take an AppInputFileValue from upload_asset's response (url + key + contentType + size + name). PITFALLS — upload_* nodes do NOT take `{ asset_id }` despite what older docs suggest — the validator wants the full file shape. Use upload_asset's url/storage_key/size_bytes/content_type/filename fields, mapping size_bytes→size, content_type→contentType, filename→name.

get_run_inputs_schema

WHAT — Generates a public read-only share link for an agent's current graph (the studio share page). Returns the full share_url — hand THAT to the user verbatim. WHEN — Use when the user wants to share their workflow with someone outside the org (link in chat, embed in a doc). For runnable sharing (inputs + run button), publish_app instead. NEXT — Return the `share_url` field to the user EXACTLY as returned — do not rewrite its domain. (`share_path`/`share_token` are also returned if you need to build the link yourself.) They can revoke at any time via unshare_agent. PITFALLS — Use the returned share_url as-is — do NOT guess or swap the host (the share page is served by the app origin, not the marketing domain). Share links carry the CURRENT graph at access time, not a snapshot — edits made later are visible to anyone with the link. Sensitive config fields (API keys, private URLs) are scrubbed automatically, but only if marked sensitive in the node definition.

share_agent

WHAT — Lists canvas comments on an agent — both free-form canvas annotations and node-bound comments — including reply threads. Returns resolved and unresolved by default. WHEN — Use before editing or rebuilding an agent to surface team feedback, reviewer notes, and open questions. Gives full context on what the team thought was wrong or worth improving. NEXT — Read the agent's graph (orisu://agents/{id}) to understand which nodes are referenced by anchor_node_id, then address the feedback in replace_graph or reply via the Orisu UI. PITFALLS — Includes resolved comments by default — pass resolved:false to see only open threads. Do NOT resolve or delete comments programmatically; humans manage comment state in the Orisu UI.

list_comments

WHAT — Lists recent runs in the current org, newest first, with optional status / agent filters. WHEN — Use whenever the user references a run without giving an id ('show me the last failed run', 'what's still running'). Cheaper than scanning orisu://runs/{id} blindly. NEXT — Pick a run_id from the results, then call orisu://runs/{run_id} for per-step outputs, asset URLs, and errors. PITFALLS — Returns at most 50 rows per call (default 20) — there is no cursor pagination here; if you need more history, walk orisu://agents/{id}/versions or filter narrower. error_summary may be null on completed/queued runs.

list_runs

WHAT — Moves an asset to trash (soft delete — sets deletedAt). It stops appearing in search / list_assets / previews immediately; a background cron purges trashed assets after 30 days. WHEN — Use when the user asks to remove/clean up a specific asset from their library. For agents use delete_agent; this is media only. NEXT — The asset is recoverable from the studio trash until the 30-day purge. To keep it, don't delete — nothing here un-trashes it (restore is a studio action). PITFALLS — Requires assets:write scope. Soft, not hard: storage bytes persist until the purge. Deleting an already-trashed or unknown id returns ASSET_NOT_FOUND (idempotent — it's already gone).

delete_asset

WHAT — Patches ONE node on an agent — config is MERGED (send only changed fields), value replaces an input node's content, label renames it. Creates a new (minor) version; node positions are preserved. WHEN — Use for any single-node change: swap a model, tweak a prompt/aspect ratio, rename. This replaces the resend-the-whole-graph pattern for small edits — reach for replace_graph only when the STRUCTURE (nodes/edges) changes. NEXT — Call trigger_run({ agent_id }) to execute with the new config. The canvas re-renders inline from this result. PITFALLS — config is a partial MERGE — never send the full config back (a stale full copy can revert concurrent changes). Keys are camelCase (aspectRatio, not aspect_ratio); check warnings[] in the result for ignored/shadowed keys. Pass base_version_id from view_agent to get VERSION_CONFLICT instead of lost updates. A config change that removes in-use dynamic ports fails with the dangling edges listed. include_graph defaults to true (full graph, for inline canvas re-render); pass false for bulk/scripted edits to get back only the patched node + version, ~10x smaller.

update_node_config

WHAT — Runs ONE pure, deterministic node (prompt_concatenator, split_text, list_selector, if_else, text_prompt, rename_asset) in isolation and returns its output. Costs 0 credits, no side effects, no agent needed. WHEN — Use while authoring to test a deterministic step — see what a prompt_concatenator joins to, how split_text tokenizes, which branch if_else takes — WITHOUT a full trigger_run. Model/billed nodes (generate_*, edit_*, generate_text, scrapers) are NOT previewable; use trigger_run for those. NEXT — Feed the previewed output shape into your GraphSpec wiring, or adjust config/inputs and preview again. Nothing is persisted. PITFALLS — inputs is keyed by INPUT PORT id (e.g. input_texts), not node id; strings are treated as text, or pass full Data envelopes. list_selector in selectionMode:'random' is non-deterministic — pin an index/first mode for a stable preview. config keys are camelCase (see orisu://nodes/{type}).

preview_node

WHAT — Renders assets inline: returns image/audio bytes as viewable/playable media content blocks, plus each asset's metadata and a permanent URL. This is HOW you show an asset to the user in the chat. WHEN — Use whenever the user wants to SEE or hear an asset — 'show me that image', 'preview the last render', 'play the audio'. Prefer this over telling the user to open a URL, and over the orisu://assets/{id} resource (many hosts, e.g. ChatGPT, can't read resource URIs from a tool flow — they answer 'Unknown resource'). NEXT — Video (no inline block exists) and oversized media return url-only — surface the url. To reuse an asset in a workflow, pass { kind, assetId } to an upload_* node input. PITFALLS — Max 8 ids per call; images/audio over ~5MB come back url-only (too big to inline). Ids from another org, or unknown ids, are reported in the text summary and skipped — never fatal.

preview_asset

WHAT — Publishes an agent as an end-user-facing app: a stable URL + input schema that anyone in the org (or beyond, if shared) can run without seeing the graph. WHEN — Use when the user wants to expose a workflow for repeated triggering ('make this a reusable tool for my team'). For one-off shares, use share_agent instead. NEXT — Return the app_id; subsequent runs are triggered via trigger_app (NOT trigger_run). The app schema is at orisu://apps/{id}. PITFALLS — Publishing pins the app to a specific version — editing the agent does NOT update the app until you re-publish. The input schema is derived from the agent's `app_input`-marked nodes; if none are marked, the app has no inputs and runs with whatever defaults the graph holds.

publish_app

WHAT — REPLACES an agent's entire graph (nodes + edges) atomically, creating a new version. WHEN — Use for substantial edits to an existing agent. For metadata-only changes (name, description, thumbnail) use update_agent. For a fresh agent use create_agent. NEXT — Call trigger_run({ agent_id }) to execute the new graph. The change renders in the in-chat canvas; no separate view is needed. PITFALLS — This is a full replacement, NOT a merge — anything not in the new spec is removed. Reuse node ids across versions when you want UI continuity; brand-new ids reset run-history attribution. Always validate_graph first; replace_graph rejects invalid specs. Pass base_version_id (from view_agent's latest_version_id) so a concurrent edit fails with VERSION_CONFLICT instead of silently overwriting it.

replace_graph

WHAT — Restores an agent's graph to a prior version, creating a new version (so history is preserved). WHEN — Use when the user wants to revert a bad edit ('undo my last change') or roll back to a known-good state. To inspect versions first, read orisu://agents/{id}/versions. NEXT — Optionally call trigger_run to verify the restored graph works. The studio canvas updates to match the restored version automatically. PITFALLS — Restoring CREATES a new version (which then becomes the latest) — it does NOT remove versions in between. Version numbers monotonically increase; you cannot revert to a previous version number, only re-apply that version's graph as a new one.

restore_version

WHAT — Revokes the public share link for an agent, returning it to private. WHEN — Use when the user explicitly asks to revoke sharing, or when sensitive content was accidentally included. NEXT — No follow-up needed. The previous share URL returns 404 immediately. PITFALLS — Anyone who already cloned the agent retains their copy — unshare only revokes future access via the link, not past actions.

unshare_agent

WHAT — Triggers an execution of a published app, validating inputs against the app's defined schema. WHEN — Use when triggering an Orisu app (published via publish_app). For triggering an agent that is NOT yet an app, use trigger_run. NEXT — Call wait_for_run({ run_id }) to block until terminal status; treat outputs same as trigger_run. PITFALLS — Read orisu://apps/{id} first to know the input schema — missing or wrong-shape inputs are rejected with VALIDATION_FAILED. The app runs against the PINNED version, not the agent's current graph; if the agent was edited after publishing, re-publish_app first.

trigger_app

WHAT — Triggers an execution of an agent's latest version, with optional input-node values for this run only. WHEN — Use after create_agent / replace_graph to actually run the workflow. For workflows already shaped as apps (with input schema), use trigger_app instead — it validates the inputs against the published schema. NEXT — Call wait_for_run({ run_id }) to block until a terminal status (completed, failed, cancelled, paused) — cheaper than polling orisu://runs/{run_id}. On 'completed', pull asset URLs from steps[]. On 'paused', the workflow is waiting on a human_review — call submit_review. PITFALLS — Inputs are a run-scoped overlay, NOT a mutation — they do not change the saved graph. Asset URLs in the run output have a TTL; download / re-upload via upload_asset if the user needs them later. Pass idempotency_key when retrying or you will spend credits twice. Runs have NO spend ceiling unless you pass max_credits — for fan-out graphs (loop edges, split_text) always set it from estimate_run_cost × safety factor.

trigger_run

WHAT — Runs an agent UP TO a target node: the node plus everything it transitively depends on (its ancestor-closure), reusing cached unchanged upstream steps. Nothing downstream of the target runs. WHEN — Use to test ONE branch of a workflow cheaply — e.g. verify a mid-graph generate step before running the whole pipeline. For the full graph, use trigger_run. NEXT — Call wait_for_run({ run_id }) to block until terminal. Outputs for the target + its ancestors are on the run; downstream nodes were not executed. PITFALLS — v1 takes NO input overrides — it runs the values already saved on the graph. Set an input value with update_node_config first, then trigger_node_run. Only the target's ancestors run; a node OUTSIDE that closure keeps whatever output it already had (or none).

trigger_node_run

WHAT — Sets the stored value of MULTIPLE input nodes (text_prompt, upload_*, element) in ONE call and ONE version bump — the bulk form of update_node_config's `value`. WHEN — Seeding a template's inputs or preparing an agent for a run — anywhere you'd otherwise chain update_node_config calls. NEXT — trigger_run, or estimate_run_cost first. PITFALLS — Values use update_node_config's exact semantics (string for text_prompt; [{ kind, assetId }] or file shape for upload_*; JSON-encoded strings parsed). Non-input node ids are reported per-node and skipped, they don't abort the batch. A MALFORMED value (e.g. a non-JSON string for an upload node) aborts the whole batch atomically — nothing persists; only unknown/non-input node ids soft-fail per-node.

set_input_values

WHAT — Soft-deletes an agent. The agent is hidden from listings and its runs cannot be triggered, but data is preserved for ~30 days for recovery. WHEN — Use when the user explicitly asks to remove a workflow. Confirm with the user first — there is no undo from the agent's perspective. NEXT — No follow-up needed. The agent disappears from orisu://agents and search({ kind: 'agent' }). PITFALLS — Soft delete, not hard delete — the data persists server-side until cleanup. Do NOT use this to 'reset' an agent for editing; that's what replace_graph is for. Triggering runs on a deleted agent will fail with NOT_FOUND.

delete_agent

WHAT — Returns ranked model variants from the @repo/models catalog, filtered by media kind + capability. WHEN — Use BEFORE create_agent / replace_graph when picking a model for a generate_* node. Cheaper and more direct than reading the whole orisu://models catalog and parsing client-side. NEXT — Use the top suggestion's variant_id as the `model` config field on the generator node. Confirm capability details with orisu://models/{variant_id} if you need exact aspect ratios / max durations. PITFALLS — Ranking is keyword match against family + variant descriptions, not semantic. If the suggestions look wrong, drop `use_case` (it's a hint, not a constraint) and pick from the unfiltered list. `aspect_ratio` is enforced strictly — typos like '16x9' drop everything.

suggest_model

WHAT — Searches the Orisu catalog by free text across one resource kind at a time. WHEN — Use whenever the user mentions a workflow / model / asset by approximate name. Cheaper and more direct than reading the whole orisu://agents or orisu://models resource and grep-ing client-side. NEXT — Pick the top result's id, then call the typed reader (orisu://agents/{id}, orisu://apps/{id}, orisu://nodes/{type}, orisu://models/{variant_id}) for full detail. To SHOW an asset hit to the user, call preview_asset({ asset_ids }) — it renders image/audio inline; do NOT rely on reading orisu://assets/{id} (tools-first hosts can't). PITFALLS — One kind per call — there is no cross-kind 'find anything'. Empty query returns everything; pass a limit. Ranking is substring + word-boundary boost, not semantic — short queries match broadly.

search

WHAT — Patches an existing brand kit — only the fields you pass change (colors, fonts, logo_url, tagline, description, voice, guidelines, name). WHEN — Use when the user corrects or extends their brand ('our primary is #C4823A now', 'add our tagline'). Read orisu://brand-kits/{id} first to see current values. NEXT — No follow-up needed — brand_* nodes referencing this kit pick up the new values on the next run. PITFALLS — Pass ONLY changed fields; omitted fields are kept, but an explicitly passed field REPLACES the whole value (colors is replaced wholesale, not merged — send the full new palette).

update_brand_kit

WHAT — Updates an agent's metadata fields (name, description, thumbnail) without touching its graph. WHEN — Use when only the metadata is changing (rename, re-describe, swap thumbnail). For graph changes, use replace_graph. NEXT — No follow-up call is needed — the update applies immediately and is visible in orisu://agents/{id}. PITFALLS — Pass ONLY the fields you want to change; omitted fields are NOT cleared. Thumbnail URLs must be publicly reachable (Orisu will re-host them — local file paths or signed URLs that expire are wrong inputs).

update_agent

WHAT — Uploads a file (via URL or data URL) into Orisu's storage and creates an asset row referencing it. WHEN — Use when the user provides external content that a workflow needs (an image to edit, a video to caption). For Orisu-generated assets, the trigger_run / trigger_app response already includes URLs. NEXT — Feed the result into trigger_run / trigger_app inputs for an upload_image / upload_video / upload_audio / upload_file node. Those nodes take EITHER an asset reference { kind, assetId } (kind ∈ image|video|audio|file — from this tool's `kind` + `asset_id`) OR the full file shape { url, key, contentType, size, name } (map storage_key→key, size_bytes→size, content_type→contentType, filename→name). They do NOT accept a bare { asset_id }. PITFALLS — Provide EITHER url OR data_url, not both. data_url is preferred for files <5MB; for larger files, host the bytes somewhere reachable and pass url — or, from a non-agent client that holds raw bytes, POST multipart/form-data to `/v1/assets/upload` (API key) which returns the same asset id without base64. Filename is optional but recommended — improves the asset's display name in orisu://assets.

upload_asset

WHAT — Reads an agent's current graph (nodes + edges + per-node config) and renders the read-only canvas inline. WHEN — Use when the user references an existing agent and you need to know its structure before editing. Cheaper than reading orisu://agents/{id} when you also want the inline visualization. NEXT — If editing: call replace_graph with the modified GraphSpec, passing this response's latest_version_id as base_version_id so a concurrent edit fails with VERSION_CONFLICT instead of being overwritten. If running: call trigger_run({ agent_id }). If branching: call clone_agent first to keep the original intact. PITFALLS — Returns the LATEST saved graph, not the in-flight version of any running execution. Run outputs are NOT in this response — fetch orisu://runs/{run_id} for those.

view_agent