Public Flows Reference

Load this reference before creating, editing, testing, releasing, promoting, or
describing public/end-user Breyta flows.

Public-Ready By Default

Assume every new or edited flow may become public unless the user explicitly
says it is internal-only. This changes how the flow is built, not whether it is
published.

Public-ready defaults:

use :requires, setup inputs, run inputs, connection slots, templates, and resources for values that vary by installer, workspace, user, region, model, file, or environment
avoid hardcoded workspace ids, user ids, emails, test resource ids, private URLs, secrets, personal accounts, and one-off local assumptions
keep outputs and timelines understandable without source code
make names, tags, descriptions, and install copy useful to the target end user

Hardcoding is acceptable only for stable public facts or documented API
constants. When a value belongs to the author, installer, or run, model it as
configuration.

Public Surfaces Are Separate

Private workspace flow: visible inside a workspace.
breyta flows search: actual workspace flow metadata.
breyta flows grep: actual workspace flow source/config search.
breyta flows templates search/grep: approved reusable template definitions to inspect and copy from.
breyta flows discover list/search: public installable catalog.
Discover visibility: stored metadata or :discover {:public true}.
Marketplace visibility: stored metadata or :marketplace {:visible true}.
Paid app catalog: stored metadata or source-authored
:marketplace {:app {... :monetization {:plans [...]}}}. Legacy
:marketplace {:monetization ...} is compatibility for existing listings,
not the preferred shape for new paid apps.
Installation: a per-user instance of an end-user flow with user-scoped prod bindings and inputs.
Activation/setup URL: the author or workspace setup surface for bindings and
saved setup inputs. It is not the public install dialog.
Discover install dialog: the public/end-user install surface. This is the
surface that proves an installable flow can be installed by an end user.

Do not use flows templates search as proof that a flow is publicly
installable. Do not use flows discover as proof that a private workspace flow
exists.

Public Flow As Reusable Tool

When another Breyta flow, hosted agent, coding agent, or external client should
reuse a public flow, install and configure the public app in the caller
workspace first when setup, billing, connections, or saved activation inputs
matter. Then choose the reuse surface by caller:

Caller	Preferred surface
Authored Breyta flow, one installed child	`flow/call-flow` with `:installation-id`
Authored Breyta flow, many installed children	`:fanout` with `{:type :call-flow ... :installation-id ...}`
Hosted or local MCP-capable agent, such as Claude, Codex, or Cursor	Workspace MCP `call_flow_tool` with `installation_id`
External non-MCP client	Installed HTTP interface
Manual smoke test or debug run	CLI/API `flows run --installation-id`

Do not hand off author draft/live endpoints as the normal consumer integration
path.

Default reuse loop:

Before source edits, direct provider setup, or template duplication, show a
visible reuse checklist: needed outputs/functions; Discover searches tried;
relevant paid apps found; and selected/rejected paid apps with reasons.
Find reusable apps in Discover with breyta flows discover search. Search
relevant Discover public and paid installable apps by requested outcome,
business function, and output modality before falling back to approved
templates or direct provider connections. For multimodal app requests, check
every needed function, including text-generation apps, image-generation apps,
video-generation apps, and any relevant paid app. For an agent that creates
ads, example searches include ad generator, copywriting,
text-generation, OpenAI image generation, image-generation, and
social ad creative.
For paid public apps, use Discover or https://breyta.ai/apps/<flow-slug>
for checkout, purchase, subscription, prepaid runs, or trial entry before
relying on the CLI/API install path.
Create, configure, and enable an installation in the caller workspace.
Inspect installation readiness with breyta flows installations get <installation-id> --pretty. Stop before wrapper design if runReadiness
reports a billing, entitlement, setup, or binding block.
Inspect the source flow's concurrency policy before manual run QA. If the
installed app should allow multiple active manual runs, avoid
:singleton :on-new-version :supersede; it intentionally replaces the
earlier run and can be mistaken for a broken installed-run UI.
Inspect callable surfaces with
breyta flows installations interfaces <installation-id>.
Smoke-test through the installation:
breyta flows interfaces call <flow-slug> <interface-id> --installation-id <installation-id> --input '{"key":"value"}' --wait.
For authored Breyta wrapper flows, use flow/call-flow or :fanout with
:installation-id; for MCP-capable agents, use workspace MCP
call_flow_tool with installation_id; for external non-MCP clients, use
the installation-scoped HTTP endpoint:
/api/flows/{flow-slug}/installations/{installation-id}/interfaces/{interface-id}.

Generic paid-app wrapper pattern:

Parent flow collects the user's inputs and any installed app ids.
Install/configure the relevant paid app in the caller workspace.
Check breyta flows installations get <installation-id> --pretty and
breyta flows installations interfaces <installation-id> before wrapper
design.
Parent flow calls the installed app with flow/call-flow and
:installation-id.
Parent flow transforms that output into the next app's input when another
relevant paid app should be chained.
Parent flow returns a polished combined output and links any generated
resources.

Authored wrapper flows must use the positional flow/call-flow contract:

(flow/call-flow :child-flow
                {:plain "child input"})

(flow/call-flow :reviewed-ai-response-generator
                {:prompt prompt
                 :intended-audience intended-audience}
                {:installation-id reviewed-ai-response-installation-id})

The third argument is the child call options map. Put :installation-id there,
not inside the child input map. The one-map form is not supported:
(flow/call-flow {:flow-slug ... :installation-id ... :input ...}).

Use installation-scoped endpoints for consumers so installer setup, auth,
billing entitlement, and ownership are applied correctly. Do not hand off author
draft/live interface URLs as the normal consumer integration path.

For MCP clients, prefer the workspace MCP server when the agent already has a
workspace-scoped MCP connection. Use search_flow_tools, inspect_flow_tool,
call_flow_tool, then get_run_status. A direct installed Streamable HTTP MCP
endpoint remains useful when a caller deliberately wants per-flow isolation.
Treat paid-flow errors such as billing_trial_ended or a returned checkout
action as billing or trial state, not as proof that the interface contract is
broken. Complete the checkout action in the web app, then retry the installation
or installed-interface call.

Known-good text-generation reuse example after checkout/readiness:

breyta flows discover search "reviewed ai response text generation" --limit 5 --pretty
# If Discover or https://breyta.ai/apps/reviewed-ai-response-generator returns
# checkout, trial, or subscription entry, complete that web step first.
breyta flows installations create reviewed-ai-response-generator --name "Reviewed AI response" --pretty
breyta flows installations get <installation-id> --pretty
breyta flows installations interfaces <installation-id> --pretty
breyta flows interfaces call reviewed-ai-response-generator generate-reviewed-response-api \
  --installation-id <installation-id> \
  --input '{"intended_audience":"founders evaluating workflow automation tools","use_case":"concise product explanation","task":"Write a two-sentence explanation of why reviewed AI output reduces editing time."}' \
  --wait --pretty

Expected success shape after checkout/entitlement/setup is complete: the
installation get response has runReadiness.ready: true; the interfaces
response includes generate-reviewed-response-api with target: "installation"; the interface call returns ok: true, a completed run/workflow
id, an outputWebUrl, and a Markdown response artifact. If
runReadiness.ready is false, resolve the reported billing, entitlement, setup,
or binding block before designing a wrapper flow. For image-generation reuse,
run the same sequence with
breyta flows discover search "image generation" and a matching image app such
as create-openai-2-image-http-mcp.

If the installed app page should support several user-started runs at once,
verify that the source flow is not using
{:concurrency {:type :singleton :on-new-version :supersede}}. That policy is
appropriate for replacement semantics, but it will intentionally make the newer
run replace the earlier in-flight run during manual QA.

Known-good authored wrapper source shape:

'(let [input (flow/input)
       reviewed-ai-response-installation-id
       (or (:reviewed-ai-response-installation-id input)
           (get input "reviewed-ai-response-installation-id"))
       prompt (or (:prompt input) (get input "prompt"))
       reviewed (flow/call-flow :reviewed-ai-response-generator
                                {:prompt prompt}
                                {:installation-id reviewed-ai-response-installation-id})]
   {:reviewed reviewed})

Using Another Creator's Paid App (Install -> Run -> Read Output)

To use a paid/marketplace app published by another creator (not one you authored),
run the installer flow end to end and read the output the way a normal user would.
This is distinct from wrapping an app inside an authored flow above; use this when
the CLI/agent itself is the consumer.

Find: breyta flows discover search "<outcome>" (not flows search/flows templates, which are your own/workspace flows).
Install: breyta flows installations create <slug> [--source-workspace-id <id> --source-flow-slug <slug>].
Check readiness: breyta flows installations get <installation-id> --pretty -> runReadiness. If ready: true (for example a no-card trial) run it. If blocked, the response carries a checkoutPath/billingUrl; a human completes that in the web app (agents cannot pay), then re-check.
Configure setup: breyta flows installations configure <installation-id> --input '{...}' --bindings '{...}' (activation fields and installer-owned connections in one call). An OAuth connection needs a one-time browser authorize first; the command consumes the resulting binding. Author-provided connections need no installer action.
Enable + run: breyta flows installations enable <installation-id>, then breyta flows run <slug> --installation-id <installation-id> --input '{...}' [--upload <field>=<path>] --wait.
Inspect + read output: breyta runs inspect <workflow-id> --installation-id <installation-id>. Installed runs require --installation-id (it is in every runs list row and the run-start response); without it runs inspect/runs events/runs step return Run not found by design. Read the final output and any res://... artifacts with breyta resources read <resource-uri>.

Installer visibility: as the installer you get the run's status, timing, final
output, and artifacts, the same view a person sees on the run page. The flow's
internal steps belong to the creator and are not exposed to installers at all:
runs inspect/runs events/runs step --installation-id return no step list,
step previews, or step captures (the response marks stepsRedacted). So do not
rely on reading another creator's step internals to verify an installed run;
verify from the final output and artifacts. (When you are the creator inspecting
your own flow's run in the source workspace, the full step captures are
available to you.)

Install And Public App Links

Do not guess install links from the current authoring page context. In
particular, do not treat an activation/setup URL such as /activate as the
public install page unless the docs or CLI output identify it as the requested
install surface.

Distinguish these surfaces when handing off public or installable work:

Authoring flow page: where the creator edits, releases, configures, and runs the flow inside the source workspace.
Activation/setup page: where a workspace configures an existing flow target or installation. This is setup, not proof of public installability.
Internal app/install surface: where a workspace user can install, configure, or run an installed app inside Breyta, commonly under the workspace Apps area.
Discover/install surface: where public installable flows are found and installed after Discover visibility is enabled.
Public marketing app page: for public flows, also provide https://breyta.ai/apps/<flow-slug> so the creator can view, share, and market the app.

When the user asks to make a flow installable:

first confirm the requested distribution: internal installable, public Discover installable, monetized, or marketplace-visible
do not treat "make this a public app" as permission to expose it to all Breyta users; ask directly before turning on Discover or marketplace visibility
load this reference before changing release, install, Discover, marketplace, or public copy behavior
release/promote only after explicit approval when required by the approval gate
enable Discover/public visibility only after the user has approved that distribution
verify the install surface through CLI/docs/UI evidence rather than inferring from the page the user happened to be viewing
when CLI/API support the approved public, pricing, listing, Discover, or marketplace change, do it directly instead of sending the user to the publish page
for new paid apps, keep plan ids stable, use at most one default/recommended
plan, and do not model seat pricing unless explicit seat entitlements exist
report every relevant URL returned by Breyta: authoring flow, setup/activation, install surface, Discover/public listing, public marketing app page, run, and run output

Approval Gate

Never set Discover or marketplace visibility without explicit flow-author
approval. The approval must say that the flow may be made accessible to all
Breyta users now. A vague request to "make it public" or "make this a public
app" is not enough.

Do not do any of the following without approval:

set :discover {:public true}
set :marketplace {:visible true}
run equivalent CLI update flags for public visibility, including
breyta flows public publish <slug>
release or promote a public/end-user flow
publish a new public description, media, or install-facing copy that materially changes user claims

When approval is needed, show the exact metadata and release/promotion command
you plan to run. Ask: "Do you want me to make this flow accessible to all Breyta
users now?" Only proceed after the author confirms and the flow is
installable-ready.

Installable Flow Checklist

Use this checklist whenever the user asks for an installable, public, Discover,
or marketplace flow. Do not stop at activation.

Confirm explicit flow-author approval for public visibility,
release/promote, install-facing copy, media, and marketplace visibility.
Configure public visibility with both :discover {:public true} and
:marketplace {:visible true} before breyta flows push --file ..., or
run breyta flows public publish <slug> after push and release.
Push, diff, release, and promote the live version after approval.
Prove owner setup separately with activation/configure/check when required.
Prove end-user installability through the Discover install dialog or an
installation create/configure/enable path.
Bind installer-owned connections and setup inputs on the installation.
Run the installed target with
breyta flows run <slug> --installation-id <installation-id> --wait.
Inspect the installed run output from the intended end-user perspective.

Report URLs for the flow, live version, activation/setup surface, Discover or
install surface, installation, installed run, run output, and any resources the
user needs to inspect. If browser access is unavailable, write
web UI not verified and include the CLI installation proof that was run.

Public Preflight Checklist

Use public-ready architecture for every new or edited flow unless the user says
it is internal-only. Run this full checklist only when the task changes public
copy, install behavior, publish/release behavior, Discover, marketplace, or
public output.

Before turning a flow public or changing public behavior, confirm these
essentials:

public-ready architecture: no hardcoded private workspace/user/test values, secrets, private URLs, or author-only assumptions
setup contract: installer-owned connections use the right :requires shape, including :provided-by :installer and :oauth where OAuth connect-first setup is needed
cost contract: external API, LLM, search, and other paid provider steps have step-level metering or cost estimates where supported; if unsupported, record that in the risk ledger
public name and slug: clear, human-readable, and aligned with the primary user query
short :description: one or two sentences covering audience, entrypoint/interface, integrations, and outcome
meta description copy: 140-160 character search snippet for review; set it only if current docs/schema expose a supported field
markdown publish description: SEO/AEO-friendly end-user landing-page copy that explains why to install, setup requirements, what happens after install, outputs, limits, and failure/permission expectations
tags: outcome, audience/use case, integration/tool, and modality tags, not only draft or internal labels
media: useful image or video when it helps users understand the actual result; flow-resource media must be a reviewed same-workspace res://... resource intended for public cards
outputs: a readable public result, usually markdown, table/media viewer, or markdown with embedded Breyta resources
verification: draft run, public/install setup path, installation-targeted run when relevant, web UI check when available, output/resource readback, and full Breyta URLs
approval: explicit flow-author approval for visibility, release/promote, marketplace, media, and install-facing claims

Setup And Run Field Planning

Treat setup and run forms as product UI for a non-technical end user. Before
creating or editing public flow fields, classify every user-supplied value:

setup-once: company profile, audience, voice, examples, default region, default folder, or other durable context reused across runs
run-each-time: prompt, file, CSV, resource picker selection, recipient, date range, row limit, or other values that naturally change per run
connection: OAuth/API/database/blob-storage accounts that should be bound through :requires
hidden/internal: implementation ids, debug toggles, author workspace state, or values the end user should not decide

Third-party accounts are setup work, not prompt text: declare connection
requirements, hand off setup/edit URLs when needed, and never ask end users to
paste secrets in chat.

For setup-once context that needs LLM processing, use setup inputs to create a
durable artifact such as a company profile, voice profile, influencer bible, or
other reusable context, then persist and reuse that context on later runs.

Keep the setup page and run form small:

use plain labels and helper text
set defaults where safe
avoid advanced/internal fields unless they are real user decisions
use :label and :title on run-collected forms so recent-run rows are readable
use viewer :breyta.viewer/options {:title ...} for viewer metadata or grouped child labels; do not rely on it to rename the canonical flow-output resource or single output chrome
treat run-list labels, viewer metadata, and persisted resource names as separate surfaces
prefer :resource fields for selecting existing artifacts, and keep manual upload available when useful

Metadata Is A Landing Page

For public/end-user flows, treat metadata and install surfaces as an end-user
landing page, not internal implementation notes.

:description is the short card/catalog summary. It should say who the flow is for, what starts it, what systems it uses, and what outcome it produces.
Tags should support discovery and clustering by outcome, audience/use case, integration/tool, and modality.
publishDescription or --publish-description-file is richer markdown for install/discover dialogs. It should explain why to install, what the user must connect or enter, what happens after install, and what output they get.
Curated Discover card media should help the user understand the actual flow or result, not decorate the listing.
Do not invent new metadata fields such as metaDescription unless product docs or schema support them.

Write the markdown publish description like a small landing page for the
intended end user:

lead with the outcome and audience
name the entrypoint/interface and connected systems in plain language
explain required setup, permissions, and inputs before the user installs
describe the output they will receive and where they will see it
include practical limits, privacy/permission expectations, and common failure cases
use headings and short sections so search engines, AI answer engines, and humans can extract the value quickly

Good public copy answers:

Who is this for?
What entrypoint or interface starts it?
What accounts, files, or inputs must the user connect?
What does it do after install?
What output does the user get?
What failure or permission cases should the user expect?

Testing Public Behavior

When public behavior matters, test through public surfaces:

use breyta flows discover list/search for catalog visibility
use breyta flows discover search "<query>" --include-own when debugging whether a flow owned by the current workspace is indexed, because normal Discover search may exclude own flows
verify the Discover install dialog; /activate alone is only owner setup proof
install or inspect installation surfaces rather than only running the private draft flow
verify activation/bindings in the user-scoped prod profile
run an installation-targeted execution when required:
- breyta flows run <slug> --installation-id <installation-id> --wait
after release/promote approval, smoke the installed target:
- breyta flows run <slug> --target live --wait
when browser/UI access is available, test the actual setup page, run form fields, upload CSV or file path, resource picker, and run output page
report full Breyta URLs for the public flow, install surface, activation, run, and run output when available

Private draft runs are useful for build iteration, but they are not sufficient
proof that public install behavior works.

End-user verification ladder:

Draft run for fast iteration.
breyta flows diff <slug> before release.
Release/promote only after explicit flow-author approval.
breyta flows show <slug> --target live.
breyta flows run <slug> --target live --wait.
Discover install dialog or installation create/configure/enable proof.
breyta flows run <slug> --installation-id <installation-id> --wait.
Web UI setup/run test when tooling and access are available.
Resource picker/upload test for resource fields, including upload CSV workflows.
Output artifact audience review.

If a browser or UI path is unavailable, do the installation-targeted CLI proof
and write web UI not verified in the risk ledger. If CLI works but UI fails,
or draft works but the setup page, run form fields, installed flow, resource
picker, or old live version fails, submit breyta feedback send with full
Breyta URLs before closing the task.

For final handoff, do not write Done for public, installable, marketplace, or
paid-flow work until the touched user-visible surfaces have been verified or
named as unverified. The minimum surface matrix is source flow, live version,
Discover listing/install surface, marketplace visibility when touched,
activation/setup when relevant, installed run when install behavior matters,
public app page, and run output.

Human Timeline Quality

Public users and operators read run timelines without source code. Keep labels
plain and outcome-based.

Add :title values for non-trivial or user-visible steps.
Use step titles that describe a human action or outcome.
Use clear manual interface labels and branch labels.
Avoid vague visible labels such as "normalize", "hydrate", "finalize", "process", or "prepare payload" unless that is truly what the user understands.

Prefer titles such as:

"Search Gmail for support emails"
"Create draft reply"
"Check whether invoice is already approved"
"Summarize run result"

Discover Card Media

For public Discover/install cards, use creator-curated media when it helps the
user understand the actual result.

Set media with breyta flows update <slug> --publish-media-type image --publish-media-source-kind https-url --publish-media-source https://....
Video media can include a poster with --publish-media-poster-kind https-url --publish-media-poster https://....
Clear media intentionally with breyta flows update <slug> --clear-publish-media.
If keeping the flow in source control, author the same value in the flow file as :publish-media.
Use alt text that explains the visible result, not implementation detail.
For --publish-media-source-kind flow-resource, use a res://... URI from
the same workspace. Treat it as public card media: use only reviewed resources
that are meant to appear on Discover/install surfaces.